def test_render_response_content_custom_mismatch(fakestate):
"""Path response's 'content' definition is NOT rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"response-examples-for": ["301", "307", "401", "422"]})
markup = textify(
testrenderer.render_response(
"200",
{
"description": "An evidence.",
"content": {
"application/json": {
"example": {
"foo": "bar",
"baz": 42
}
}
},
},
))
assert markup == textwrap.dedent(f"""\
:statuscode 200:
An evidence.
""".rstrip())
def test_render_paths_methods_order_insensitive(fakestate, oas_fragment):
"""Paths definition is rendered with HTTP methods ordered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"http-methods-order": ["gEt", "post"]})
markup = textify(
testrenderer.render_paths(
oas_fragment("""
/evidences:
post:
responses:
'201':
description: An evidence created.
get:
responses:
'200':
description: A list of evidences.
""")))
assert markup == textwrap.dedent("""\
.. http:get:: /evidences
:statuscode 200:
A list of evidences.
.. http:post:: /evidences
:statuscode 201:
An evidence created.
""")
def test_render_request_body_example_preference(fakestate,
example_preference_key):
"""Request body's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {example_preference_key: ["text/plain"]})
markup = textify(
testrenderer.render_request_body_example(
{
"content": {
"application/json": {
"example": {
"foo": "bar",
"baz": 42
}
},
"text/plain": {
"example": 'foo = "bar"\nbaz = 42'
},
}
},
"/evidences/{evidenceId}",
"POST",
))
assert markup == textwrap.dedent("""\
.. sourcecode:: http
POST /evidences/{evidenceId} HTTP/1.1
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip())
def test_render_response_header_description_restructuredtext(fakestate):
"""Path response's 'header' description can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_response(
200,
{
"description": "An evidence.",
"headers": {
"X-Request-Id": {
"description": "A unique __request__\n`identifier`.",
}
},
},
))
assert markup == textwrap.dedent("""\
:statuscode 200:
An evidence.
:resheader X-Request-Id:
A unique __request__
`identifier`.
""".rstrip())
def test_render_response_content_custom(fakestate, oas_fragment, status_code,
status):
"""Path response's 'content' definition is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"response-examples-for": ["301", "307", "401", "422"]})
markup = textify(
testrenderer.render_response(
status_code,
oas_fragment("""
description: An evidence.
content:
application/json:
example:
foo: bar
baz: 42
"""),
))
assert markup == textwrap.dedent(f"""\
:statuscode {status_code}:
An evidence.
.. sourcecode:: http
HTTP/1.1 {status_code} {status}
Content-Type: application/json
{{
"foo": "bar",
"baz": 42
}}
""".rstrip())
def test_render_operation_description_commonmark_restructuredtext(
fakestate, oas_fragment):
"""Operation's 'description' can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_operation(
"/evidences",
"post",
oas_fragment("""
description: __Create__ an `evidence`.
responses:
'201':
description: An evidence created.
"""),
))
assert markup == textwrap.dedent("""\
.. http:post:: /evidences
__Create__ an `evidence`.
:statuscode 201:
An evidence created.
""".rstrip())
def test_render_response_content_example_preference_complex(
fakestate, example_preference_key):
"""Path response's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{example_preference_key: ["application/json", "text/plain"]})
markup = textify(
testrenderer.render_response_content(
{
"text/csv": {
"example": "foo,baz\nbar,42"
},
"text/plain": {
"example": 'foo = "bar"\nbaz = 42'
},
"application/json": {
"schema": {
"type": "object"
}
},
},
"200",
))
assert markup == textwrap.dedent("""\
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip())
def test_render_response_header_description_restructuredtext(
fakestate, oas_fragment):
"""Path response's 'header' description can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_response(
200,
oas_fragment("""
description: An evidence.
headers:
X-Request-Id:
description: |
A unique __request__
`identifier`.
"""),
))
assert markup == textwrap.dedent("""\
:statuscode 200:
An evidence.
:resheader X-Request-Id:
A unique __request__
`identifier`.
""".rstrip())
def test_render_operation_description_commonmark(fakestate):
"""Operation's 'description' can be in commonmark."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "commonmark"})
markup = textify(
testrenderer.render_operation(
"/evidences",
"post",
{
"description": "__Create__ an `evidence`.",
"responses": {
"201": {
"description": "An evidence created."
}
},
},
))
assert markup == textwrap.dedent("""\
.. http:post:: /evidences
**Create** an ``evidence``.
:statuscode 201:
An evidence created.
""".rstrip())
def test_render_response_example_preference_priority(fakestate, oas_fragment):
"""Path response's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{
"example-preference": ["application/json"],
"response-example-preference": ["text/plain"],
},
)
markup = textify(
testrenderer.render_response_example(
oas_fragment("""
application/json:
example:
foo: bar
baz: 42
text/plain:
example: |
foo = "bar"
baz = 42
"""),
"200",
))
assert markup == textwrap.dedent("""\
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip())
def test_render_parameter_header_description_restructuredtext(fakestate, oas_fragment):
"""Header parameter's 'description' can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"markup": "restructuredtext"}
)
markup = textify(
testrenderer.render_parameter(
oas_fragment(
"""
name: evidenceId
in: header
description: |
A unique evidence `identifier`
to __query__.
"""
)
)
)
assert markup == textwrap.dedent(
"""\
:reqheader evidenceId:
A unique evidence `identifier`
to __query__.
""".rstrip()
)
def test_render_parameter_path_description_commonmark(fakestate, oas_fragment):
"""Path parameter's 'description' can be in commonmark."""
testrenderer = renderers.HttpdomainRenderer(fakestate, {"markup": "commonmark"})
markup = textify(
testrenderer.render_parameter(
oas_fragment(
"""
name: evidenceId
in: path
required: true
description: |
A unique evidence `identifier`
to __query__.
"""
)
)
)
assert markup == textwrap.dedent(
"""\
:param evidenceId:
A unique evidence ``identifier``
to **query**.
:paramtype evidenceId: required
""".rstrip()
)
def test_render_request_body_schema_description_turned_off(
fakestate, oas_fragment):
"""JSON schema description is not rendered b/c feature is off."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{"no-json-schema-description": True},
)
markup = textify(
testrenderer.render_request_body(
oas_fragment("""
content:
application/json:
schema:
properties:
foo:
type: string
bar:
type: integer
"""),
"/evidences/{evidenceId}",
"POST",
))
assert markup == textwrap.dedent("""\
""")
def test_render_request_body_example_preference(fakestate, oas_fragment,
example_preference_key):
"""Request body's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {example_preference_key: ["text/plain"]})
markup = textify(
testrenderer.render_request_body_example(
oas_fragment("""
content:
application/json:
example:
foo: bar
baz: 42
text/plain:
example: |
foo = "bar"
baz = 42
"""),
"/evidences/{evidenceId}",
"POST",
))
assert markup == textwrap.dedent("""\
.. sourcecode:: http
POST /evidences/{evidenceId} HTTP/1.1
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip())
def test_render_responses_json_schema_description_turned_off(
fakestate, oas_fragment):
"""JSON schema description is not rendered b/c feature is off."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{"no-json-schema-description": True},
)
markup = textify(
testrenderer.render_responses(
oas_fragment("""
'200':
description: An evidence.
content:
application/json:
schema:
properties:
foo:
type: string
bar:
type: integer
""")))
assert markup == textwrap.dedent("""\
:statuscode 200:
An evidence.
""")
def test_render_paths_methods_order_custom(fakestate):
"""Paths definition is rendered with HTTP methods ordered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{"http-methods-order": ["delete", "options", "get", "post"]})
markup = textify(
testrenderer.render_paths(
{
"/evidences": {
"post": {
"responses": {
"201": {
"description": "An evidence created."
}
},
},
"options": {
"responses": {
"200": {
"description": "CORS preflight request."
},
},
},
"get": {
"responses": {
"200": {
"description": "A list of evidences."
}
},
},
}
}, ))
assert markup == textwrap.dedent("""\
.. http:options:: /evidences
:statuscode 200:
CORS preflight request.
.. http:get:: /evidences
:statuscode 200:
A list of evidences.
.. http:post:: /evidences
:statuscode 201:
An evidence created.
""")
def test_render_response_description_restructuredtext(fakestate):
"""Path response's 'description' can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_response(
"200",
{"description": "An __evidence__ that matches\nthe `query`."}))
assert markup == textwrap.dedent("""\
:statuscode 200:
An __evidence__ that matches
the `query`.
""".rstrip())
def test_oas3_generate_examples_from_schema(fakestate, oas_fragment):
"""Schema can be used to generate example snippets."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"generate-examples-from-schemas": True})
markup = textify(
testrenderer.render_restructuredtext_markup(
oas_fragment("""
openapi: 3.0.3
info:
title: An example spec
version: 1.0
paths:
/test:
get:
description: an operation description
responses:
'200':
content:
application/json:
schema:
items:
format: int32
type: integer
type: array
description: a response description
""")))
assert markup == textwrap.dedent("""\
.. http:get:: /test
an operation description
:statuscode 200:
a response description
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
[
1,
1
]
""")
def test_render_response_description_commonmark(fakestate, oas_fragment):
"""Path response's 'description' can be in commonmark."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "commonmark"})
markup = textify(
testrenderer.render_response(
"200",
oas_fragment("""
description: |
An __evidence__ that matches
the `query`.
"""),
))
assert markup == textwrap.dedent("""\
:statuscode 200:
An **evidence** that matches
the ``query``.
""".rstrip())
def test_render_parameter_query_description_commonmark(fakestate):
"""Query parameter's 'description' can be in commonmark."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "commonmark"})
markup = textify(
testrenderer.render_parameter({
"name":
"evidenceId",
"in":
"query",
"description":
"A unique evidence `identifier`\nto __query__.",
}))
assert markup == textwrap.dedent("""\
:queryparam evidenceId:
A unique evidence ``identifier``
to **query**.
""".rstrip())
def test_render_parameter_header_description_restructuredtext(fakestate):
"""Header parameter's 'description' can be in restructuredtext."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_parameter({
"name":
"evidenceId",
"in":
"header",
"description":
"A unique evidence `identifier`\nto __query__.",
}))
assert markup == textwrap.dedent("""\
:reqheader evidenceId:
A unique evidence `identifier`
to __query__.
""".rstrip())
def test_render_response_content_example_preference_complex(
fakestate, example_preference_key, oas_fragment
):
"""Path response's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {example_preference_key: ["application/json", "text/plain"]}
)
markup = textify(
testrenderer.render_response_content(
oas_fragment(
"""
text/csv:
example: |
foo,baz
bar,42
text/plain:
example: |
foo = "bar"
baz = 42
application/json:
schema:
type: object
"""
),
"200",
)
)
assert markup == textwrap.dedent(
"""\
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip()
)
def test_render_response_content_custom_mismatch(fakestate, oas_fragment):
"""Path response's 'content' definition is NOT rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"response-examples-for": ["301", "307", "401", "422"]})
markup = textify(
testrenderer.render_response(
"200",
oas_fragment("""
description: An evidence.
content:
application/json:
example:
foo: bar
baz: 42
"""),
))
assert markup == textwrap.dedent(f"""\
:statuscode 200:
An evidence.
""".rstrip())
def test_render_json_schema_description_description_restructuredtext(
fakestate, oas_fragment, req_or_res, directive, typedirective):
"""JSON schema description is generated with reStructuredText description."""
testrenderer = renderers.HttpdomainRenderer(fakestate,
{"markup": "restructuredtext"})
markup = textify(
testrenderer.render_json_schema_description(
oas_fragment("""
type: object
description: a resource representation
properties:
created_at:
type: string
description: a `resource` creation __time__
"""),
req_or_res,
))
assert markup == textwrap.dedent(f"""\
:{directive} created_at:
a `resource` creation __time__
:{typedirective} created_at: string
""".rstrip())
def test_render_response_content_example_preference_priority(fakestate):
"""Path response's example from preferred media type is rendered."""
testrenderer = renderers.HttpdomainRenderer(
fakestate,
{
"example-preference": ["application/json"],
"response-example-preference": ["text/plain"],
},
)
markup = textify(
testrenderer.render_response_content(
{
"application/json": {
"example": {
"foo": "bar",
"baz": 42
}
},
"text/plain": {
"example": 'foo = "bar"\nbaz = 42'
},
},
"200",
))
assert markup == textwrap.dedent("""\
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: text/plain
foo = "bar"
baz = 42
""".rstrip())
def testrenderer(fakestate):
return renderers.HttpdomainRenderer(fakestate, {})
def test_render_parameters_case_insensitive(fakestate, oas_fragment):
"""Many parameter definitions are rendered w/ preserved order."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"request-parameters-order": ["QUERY", "pAth", "Header"]})
markup = textify(
testrenderer.render_parameters(
oas_fragment("""
- name: kind
in: PATH
required: true
description: An evidence kind.
schema:
type: string
- name: Api-Version
in: header
default: '1'
description: API version to use for the request.
schema:
type: integer
- name: details
in: query
description: If true, information w/ details is returned.
schema:
type: boolean
- name: evidenceId
in: Path
required: true
description: A unique evidence identifier to query.
schema:
type: string
- name: related
in: qUery
description: If true, links to related evidences are returned.
schema:
type: boolean
- name: Accept
in: headeR
default: application/json
description: A desired Content-Type of HTTP response.
schema:
type: string
""")))
assert markup == textwrap.dedent("""\
:queryparam details:
If true, information w/ details is returned.
:queryparamtype details: boolean
:queryparam related:
If true, links to related evidences are returned.
:queryparamtype related: boolean
:param kind:
An evidence kind.
:paramtype kind: string, required
:param evidenceId:
A unique evidence identifier to query.
:paramtype evidenceId: string, required
:reqheader Api-Version:
API version to use for the request.
:reqheadertype Api-Version: integer
:reqheader Accept:
A desired Content-Type of HTTP response.
:reqheadertype Accept: string
""".rstrip())
def test_render_parameters_case_insensitive(fakestate):
"""Many parameter definitions are rendered w/ preserved order."""
testrenderer = renderers.HttpdomainRenderer(
fakestate, {"request-parameters-order": ["QUERY", "pAth", "Header"]})
markup = textify(
testrenderer.render_parameters([
{
"name": "kind",
"in": "PATH",
"required": True,
"description": "An evidence kind.",
"schema": {
"type": "string"
},
},
{
"name": "Api-Version",
"in": "header",
"default": "1",
"description": "API version to use for the request.",
"schema": {
"type": "integer"
},
},
{
"name": "details",
"in": "query",
"description": "If true, information w/ details is returned.",
"schema": {
"type": "boolean"
},
},
{
"name": "evidenceId",
"in": "Path",
"required": True,
"description": "A unique evidence identifier to query.",
"schema": {
"type": "string"
},
},
{
"name": "related",
"in": "qUery",
"description":
"If true, links to related evidences are returned.",
"schema": {
"type": "boolean"
},
},
{
"name": "Accept",
"in": "headeR",
"default": "application/json",
"description": "A desired Content-Type of HTTP response.",
"schema": {
"type": "string"
},
},
]))
assert markup == textwrap.dedent("""\
:queryparam details:
If true, information w/ details is returned.
:queryparamtype details: boolean
:queryparam related:
If true, links to related evidences are returned.
:queryparamtype related: boolean
:param kind:
An evidence kind.
:paramtype kind: string, required
:param evidenceId:
A unique evidence identifier to query.
:paramtype evidenceId: string, required
:reqheader Api-Version:
API version to use for the request.
:reqheadertype Api-Version: integer
:reqheader Accept:
A desired Content-Type of HTTP response.
:reqheadertype Accept: string
""".rstrip())
