sphinx-contrib / openapi

OpenAPI (fka Swagger) spec renderer for Sphinx.

sphinxcontrib-openapi

sphinxcontrib-openapi is a Sphinx extension to generate APIs docs from OpenAPI (fka Swagger) spec. It depends on sphinxcontrib-httpdomain that provides an HTTP domain for describing RESTful HTTP APIs, so we don't need to reinvent the wheel.

$ python3 -m pip install sphinxcontrib-openapi

Usage

Pass sphinxcontrib-openapi to extensions list in Sphinx's conf.py

extensions = [
   ...
   'sphinxcontrib.openapi',
]

and feel free to use the openapi directive to render OpenAPI specs

.. openapi:: path/to/openapi.yml

Links

• Documentation: https://sphinxcontrib-openapi.readthedocs.org/
• Source: https://github.com/sphinx-contrib/openapi
• Bugs: https://github.com/sphinx-contrib/openapi/issues

openapi's Issues

Local file references broken on windows

Windows 10, Python 3.9, Sphinx==3.5.3

Exception occurred:
  File "C:\Users\aye\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\jsonschema\validators.py", line 782, in resolve_from_url
    raise exceptions.RefResolutionError(exc)
jsonschema.exceptions.RefResolutionError: <urlopen error [WinError 3] The system cannot find the path specified: '\\definitions\\foo.yml'>

I am using the same test case as #3 does and getting the above error.

A little poking around shows that the base uri is being set to file://H:\projects\XXX\source\api_spec.yml and the reference is trying to resolve file://H:\projects\XXX\source\api_spec.yml/definitions/foo.yml

After getting this error I tried the latest dev versions with no changes (sphinxcontrib-openapi version 0.7.1.dev12+g4f78db9 and jsonschema-3.2.1.dev362+g833b6a9).

Schemas are assumed to be objects, not type combinators

openapi/sphinxcontrib/openapi/openapi30.py

Line 260 in 547f645

yield indent + ':param {type} {name}:'.format(

This line assumes that every schema it operates on will be {type: string}, {type: object} or soforth, and fails to support the type combinators anyOf, oneOf and allOf when they occur at the top level. While I appreciate that providing a meaningful rendering of such types is challenging, it'd be awesome if the openapi plugin could at least fail gracefully and let a user know what killed it.

  File "sphinxcontrib/openapi/openapi30.py", line 262, in _httpresource
    type=param['schema']['type'],
KeyError: 'type'

isn't a great UX and hunting down what part of my spec was killing Sphinx took a hot second.

Introduce normalization level

Since 9ca1e0a we started passing parameters argument to _httpresource. The reason is to enable endpoint's root-level parameters option. However, it doesn't seem right to keep extending the function interface each time we need to support rare case. Instead, it'd be better to introduce some normalization level where we process the spec, and then pass to render function that knows nothing about edge cases.

Enhance resolving of JSON references

OpenAPI spec may contain JSON references, so before trying to render the spec we've got to properly resolve them.

There are two drawbacks in current implementation.

1. Resolver doesn't resolve recursive references, e.g. if A refers to B and B refers to C after processing A will contain B with unresolved C.

2. JSON references don't support external YAMLs which may be inconvenient in case of OpenAPI specs (YAML is more readable).

Both points above require complete rewriting of ref resolver, and that's why they weren't solved at the first place.

Restructure docs to reflect recents changes in renderers

The extension now supports multi-renderers architecture, which means we can have more than one renderer to render the OpenAPI spec. Each renderer may have its own set of configuration options, and so we need to update the docs to reflect these changes.

[feature request]: table of contents of paths/methods

Generating a table of contents with direct links to the included paths/methods would be helpful when the generated documentation is long (e.g. when there are many paths/methods, when several or long examples are included).

openapi doesn't work with sphinx 1.6.1

$ make html
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.6.1
making output directory...
loading translations [ja]... 
/usr/local/lib/python3.6/site-packages/sphinxcontrib/openapi.py:23: RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use the standard library version instead.
  from sphinx.util.compat import Directive

Exception occurred:
  File "/usr/local/lib/python3.6/site-packages/sphinxcontrib/openapi.py", line 195, in setup
    if 'http' not in app.domains:
AttributeError: 'Sphinx' object has no attribute 'domains'
The full traceback has been saved in /tmp/sphinx-err-f5_cfbju.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:55: recipe for target 'html' failed
make: *** [html] Error 1

I think sphinx-doc/sphinx#3760 is same issue.

Unable to resolve local relative file references

I have two yml files that define my Swagger specification:

# api_spec.yml
...
paths:
  /foo:
    get:
      summary: Foo List
      description: Lists all foos
      produces:
        - application/json
      responses:
        "200":
          description: A list of Foo objects
          schema:
            type: array
            items:
              $ref: ./definitions/foo.yml#/Foo
...

and

# definitions/foo.yml
Foo:
  type: object
  properties:
    id:
      type: string
      description: Unique id for foo
    label:
      type: string
      description: Human-readable description of foo

When I attempt to build my sphinx docs, I get the following error:

building [html]: targets for 13 source files that are out of date
updating environment: 13 added, 0 changed, 0 removed
reading sources... [  7%] api_reference                                                                                                           
Exception occurred:
  File "/usr/local/lib/python2.7/site-packages/jsonschema/validators.py", line 346, in resolve_from_url
    raise RefResolutionError(exc)
RefResolutionError: unknown url type: ./definitions/scenario.yml
The full traceback has been saved in /tmp/sphinx-err-7U659m.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:58: recipe for target 'html' failed
make: *** [html] Error 1

It appears that jsonschema.RefResolver is always instantiated with base_uri = '', which would break local refs. Is it possible to have an option on the openapi directive that would allow local file refs in the Swagger definition somehow?

It appears that some workarounds are being explored here: python-jsonschema/jsonschema#313 (comment)

(Question) How provide dynamic openapi file

Hello in the documentation you guys show how to provide a physical openapi file, but I would like to pass a url to it : https://petstore.swagger.io/v2/swagger.json

New release

I'd like to use the OpenAPI 3.0.0 support in one of my projects. Any chance we could get a 0.4/1.0 release so I can do so? I guess #16 could go in first, though some rework seems necessary there first.

Support for OpenAPI v3

Hi! Are there any plans for supporting OpenAPI 3.x? PR #17 fixes at least one blocking bug, but it wasn't merged.

Array of string or integer doesn't show its description

Hi,

When having a property like this:

      permissions:
        description: Actuators allowed
        example:
        - a0
        - a1
        items:
          type: string
        type: array

I get an output where description is not shown:

result.acl[].permissions[] (string) –

In cases like this (or array of integers maybe) it would be nice to show the description.

0.7.0: sphinx warnings

Sphinx shows some warnings on generate sphinxcontrib-openapi modiule documentation

[tkloczko@barrel openapi-0.7.0]$ SETUPTOOLS_SCM_PRETEND_VERSION=0.7.0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.1.2
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
<openapi>:1: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... sphinxcontrib-openapi.1 { } done
build succeeded, 17 warnings.

Unexpected KeyError with simple descriptor

sphinx 2.4.4 +
sphinxcontrib-openapi in /usr/local/lib/python3.7/site-packages (0.7.0)

test-0.1.yml:

openapi: 3.0.1
info:
  title: the title
  description: A nice API
  contact:
    name: Fred
    url: https://gigantic-server.com
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://foo.bar
  version: "v1.1"

RST file content:

.. openapi:: test-0.1.yml

sphinx-build -b html -d build/doctrees source build/html
Running Sphinx v2.4.4
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [ 72%] operator-setup
Exception occurred:
File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/utils.py", line 105, in normalize_spec
for endpoint in spec['paths'].values():
KeyError: 'paths'
The full traceback has been saved in /var/folders/kw/y4ys06qn4bx8lww9yszq5h480000gn/T/sphinx-err-xwso7dyr.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at https://github.com/sphinx-doc/sphinx/issues. Thanks!

log file:

...
  File "/usr/local/lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.7/site-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python3.7/site-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2344, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/local/lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_construct
    return method(self, expmatch)
  File "/usr/local/lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2099, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/local/lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2148, in run_directive
    result = directive_instance.run()
  File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/directive.py", line 56, in run
    return renderer_cls(self.state, self.options).render(spec)
  File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/renderers/abc.py", line 40, in render
    for line in self.render_restructuredtext_markup(spec):
  File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/renderers/_httpdomain_old.py", line 42, in render_restructuredtext_markup
    utils.normalize_spec(spec, **self._options)
  File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/utils.py", line 105, in normalize_spec
    for endpoint in spec['paths'].values():
KeyError: 'paths'

Examples with a 'byte' string generate an error

When a schema contains a string attribute of format byte and when the examples option is set, the following error is generated:
TypeError: Object of type 'bytes' is not JSON serializable
The _TYPE_MAPPING in openapi30.py should reference a string and not bytes.

Will path references be supported?

I noticed that API specs with $ref path objects cause an error. Is that something that will be supported in the future?

response content schema elements missing on OpenAPI 3.0

I've been using Sphinx OpenAPI previously with OpenAPI 2.0 specs. Now I'm dealing with my first OpenAPI 3.0 spec, and I've noticed that I can't find a "Response JSON Object" section on the different end-points. The schema is defined in the content element's content type (application/json) definition. The content is definitely in the spec (YAML file) and ReDoc as well as SwaggerUI show it.

Or am I doing anything wrong? I'm happy to provide further details.

recursion limit exceeded (and seg faults with increased python recursion limit)

I believe there is an infinite loop in the recursion in the utils _do_resolve function. I have tried to replicate the issue from building out some of my own config files but haven't been able to do so. I have supplied our config file since its what is currently causing the issue in hopes that you have a better grasp than myself on what the issue might be.

Most of the Objects in this are either a LocalPlugin or RemotePlugin.
Some history behind our configuration file here. Our project is an open source Spring boot project (https://github.com/racker/salus-telemetry-monitor-management) and we are generating the swagger from https://github.com/kongchen/swagger-maven-plugin.
Github doesn't allow the uploading of yml files so I just changed the extension.
swagger.txt

Please let me know if you need more information or clarification from me.

References not resolved within lists

References nested with in a list will not be resolved. For example, the following YAML code:

paths:
  /batches:
    post:
      summary: Sends a BatchList to the validator
      consumes:
        - application/octet-stream
      parameters:
        -
          name: BatchList
          in: body
          description: A binary encoded protobuf BatchList
          schema:
            $ref: "#/definitions/BatchList"
          required: true
        -
          $ref: "#/parameters/callback"

Neither reference will be caught by _resolve_refs.

sphinxcontrib-openapi can't render free-form object

with below swagger file.

...
paths:
  /Pool/{poolID}/users/{userID}:
      post:
        operationId: addPlayer
        parameters:
          - $ref: "#/parameters/PoolID"
          - $ref: "#/parameters/UserID"
          - $ref: "#/parameters/PlayerData"
...
parameters:
  PoolID:
    in: path
    name: poolID
    required: true
    type: string
  UserID:
    in: path
    name: userID
    required: true
    type: string
    description: "The user ID"
  PlayerData:
    in: "body"
    name: "data"
    required: true
    schema:
      type: "object"
      additionalProperties: true
...

The rendered doc only got the PoolID and UserID. PlayerData got lost.

Display openapi Schema object in generated sphinx documentation

Implemented here: #20

You can see an example of documentation generated here:
https://asterios.readthedocs.io/en/new-api/api.html#post--game-config
Using this openapi.yml file:
https://github.com/Maillol/asterios/blob/new-api/spec/openapi.yml

Note:

• The shema is displayed for all request. perhaps is better if this behavior is optional.
• We cannot display shema for each response type because sphinx http domain merges all shema so I display only shema of success response.

Exception raised on enum query parameters without "type"

JSON Schema does not require "type" to be present for enums, see also https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values.

The plugin however requires it for all query parameter schemas:

openapi/sphinxcontrib/openapi/openapi30.py

Lines 279 to 282 in 4f78db9

	for param in filter(lambda p: p['in'] == 'query', parameters):
	yield indent + ':query {type} {name}:'.format(
	type=param['schema']['type'],
	name=param['name'])

Sample error:

2021-01-12T14:38:38.9415027Z Exception occurred:
2021-01-12T14:38:38.9416063Z   File "/__w/1/s/env/lib/python3.8/site-packages/sphinxcontrib/openapi/openapi30.py", line 281, in _httpresource
2021-01-12T14:38:38.9416591Z     type=param['schema']['type'],
2021-01-12T14:38:38.9416959Z KeyError: 'type'

Sample parameter:

          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "PENDING",
                "TRUSTED",
                "RETIRED"
              ]
            }
          }

An unused page "HTTP Routing Table" when generating pdf by rst2pdf

Currently, I'm using this extension to help me generate a pdf document, and I found when using this with rst2pdf.pdfbuilder , it would generate an extra page like

And this page is generated by httpdomain extension if we didn't set up noindex option under the directives.
Is there any side effect if we do this change? (function _httpresource under openapi20.py and openapi30.py)
Or any other options to avoid this routing table page?

Thanks

Type error thrown when schema uses oneOf

schema:

    oneOf:  

         - type: array  

         - type: string 

Will throw

Exception occurred: File "/Users/maxmurmann/opt/anaconda3/envs/bullhorn-apis/lib/python3.8/site-packages/sphinxcontrib/openapi/openapi30.py", line 282, in _httpresource type=param['schema']['type'], KeyError: 'type'

whereas I believe this should be a fine formatting for OpenAPI?

Output json schema to sphinx doc page for an endpoint using openapi 2.0

Is there anyway to do this?

Incompatiable with OpenApi 3.0.1

Brief Introduction:
We are facing issues while generating the sphinx documentation while using openAPI 3.0.1 yml template files .
But it works successful with the Swagger 2.0 template.

Ask:
Can you please confirm if sphinx supports OpenAPI 3.01 templates for documentation?

Problem Statement :
Specifically, we are facing issues for following parameters in documentation.
a) Request Json Parameters
b) Response Json Parameters

As per below example of Open API 3.01 template it expects

( schema property is child of content)

where as in Swagger 2.0 the structure looks like this.

if we use the Swagger 2.0 yml to generate the HTML documentation then I successfully generates the Request JSON Parameter and Response JSON Parameters as below.

where as with former with openAPI 3.0.1 template it failed to load these request Json parameter and response Json Parameters

You can refer any sample open API 3.0.1 template from internet to reproduce this issue.

Really appreciate your prompt support.

[feature request]: Filter by method for a path

I am using the directive to include some generated API doc into my documentation, and thus using the :paths: parameter.

Would it be possible to select a list of method for each path, to avoid displaying all methods for a path ?

Like:

.. openapi:: my_spec.yml
   :paths:
      /resource[get,delete]
   :encoding: utf-8

Thanks !

OpenAPI v3: RequestBody should support OneOf, AnyOf

According to https://swagger.io/docs/specification/describing-request-body/ "OneOf" is a valid element to describe alternate schemas in the request body.

`sphinx-build -W` raises an exception

Hi there,

because our team would like to validate the correctness of Sphinx-syntax in our docstrings, we intend to use the -W parameter of sphinx-build. Unfortunately, this also converts this warning into an exception:

Traceback (most recent call last):
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/application.py", line 337, in build
    self.builder.build_all()
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 257, in build_all
    self.build(None, summary=__('all source files'), method='all')
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 307, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/contextlib.py", line 120, in __exit__
    next(self.gen)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 213, in pending_warnings
    memhandler.flushTo(logger)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 178, in flushTo
    logger.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1599, in handle
    self.callHandlers(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1661, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 950, in handle
    rv = self.filter(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 811, in filter
    result = f.filter(record)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 423, in filter
    raise exc
sphinx.errors.SphinxWarning: <openapi>:1:Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.

Warning, treated as error:
<openapi>:1:Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.

Versions

Sphinx                         4.1.2
sphinxcontrib-httpdomain       1.7.0
sphinxcontrib-openapi          0.7.0

Steps to Reproduce

In one of the documents I have added the openapi directive:

.. openapi:: ./openapi_trunc.yml

The contents of the schema look like this (truncated, but still causing the warning):

openapi: 3.0.2
info:
  title: 'SMELT'
  version: 'v1'
paths:
  /reports/maintenance/monthly_group_{group_name}/:
    get:
      operationId: retrieveMonthlyReportGroup
      description: Add links to all reports to context
      parameters:
      - name: group_name
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: ''
      tags:
      - reports

Build command: sphinx-build -W -a -T -b html source/ /tmp/html/

Expected behavior

Unfortunately, I'm not familiar with the Sphinx internals, but my guess: If the role does not exist, it should not be used.

type = param['schema']['type'] breaks in newer spec

PROBLEM:
In the newest spec and pydantic capability you can give multiple types for validation. When I do a make html this breaks as there is not type key under param['schema']. Rather you now have anyof as a key and a list of types of which a type might have a format as an alternative.
In file sphinxcontrib/openapi/openapi30.py, starting on line 270

for param in filter(lambda p: p['in'] == 'path', parameters):
        yield indent + ':param {type} {name}:'.format(
           type=param['schema']['type'],
           name=param['name'])

This can be changed to the following to fix:

for param in filter(lambda p: p['in'] == 'path', parameters):
        if 'type' in param['schema'].keys():
            dtype = param['schema']['type']
        else:
            dtype = set()
            for t in param['schema']['anyOf']:
                if 'format' in t.keys():
                    dtype.add(t['format'])
                else:
                    dtype.add( t['type'])
        yield indent + ':param {type} {name}:'.format(
           type = dtype,
           name=param['name'])

This then gives an output of
Parameters componentid ({'uuid', 'integer', 'string'}) –

Parameters at path roots are mishandled

openapi2httpdomain assumes all keys at the root level of paths are HTTP Methods, but according to the Open API spec, they can also be parameters which will be passed down to all methods at that route. For example, the following YAML will not build:

paths:
  /state/{merkel_root}:
    parameters:
      - $ref: "#/parameters/merkel_root"
    get:
      . . .
    post:
      . . .

Setting host for examples in openapi3

When rendering examples using an openapi3 yaml file, the host isn't selected from the list of servers but replace with example.com

Support OpenAPI v3 parameters content

document generation crashes with:

Exception occurred:
  File ".../venv_sphinx/lib/python3.6/site-packages/sphinxcontrib/openapi/openapi30.py", line 281, in _httpresource
    type=param['schema']['type'],
KeyError: 'schema'

since it does not seem to support parameters with content

https://swagger.io/docs/specification/describing-parameters/

setuptools as runtime requirement?

I'm not quite sure but from here:

openapi/sphinxcontrib/__init__.py

Line 12 in 3990512

__import__('pkg_resources').declare_namespace(__name__)

it seems like setuptools (_scm?) should also be a runtime requirement. What am I missing here?

I maintain the conda-forge feedstock for this package and it seems that CI fails white testing a basic import sphinxcontrib.openapi due to missing pkg_resources. Any hint?

Thanks!

"$ref" sections are not rendered at all even if they are defined in the same file.

I am using sphinx to render the openapi.yml file given in the documentation of the package, but in the output there is no section Response JSON Object that is corresponding to the $ref defined in the yaml file. I have tried with other yaml files as well but it is the same for all of them. I googled the issue as well but I could not find any answer. Now I am wondering is it a bug with openapi or am I missing something?

I am following the documentation step by step meaning:

• added the given example yaml file to a directory named specs/openapi.yml
• added this line to my .rst file: .. openapi:: specs/openapi.yml
• ran sphinx-build command as usual

I am using the latest version of the required packages:
sphinxcontrib-openapi: 0.4.0
sphinxcontrib-httpdomain: 1.7.0
pyyaml: 5.1.2
jsonschema: 3.0.2
python: 3.6.9

[feature request]: support filter by not only path but also request method

0.7.0: pytest warning

I'm trying to package your module as an rpm package. So I'm using the typical build, install and test cycle used on building packages from non-root account.

• "setup.py build"
• "setup.py install --root </install/prefix>"
• "pytest with PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-openapi-0.7.0-4.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-openapi-0.7.0-4.fc35.x86_64/usr/lib/python3.8/site-packages
+ /usr/bin/pytest -ra --import-mode=importlib tests/ --strict -p no:randomly
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.11, pytest-6.2.5, py-1.10.0, pluggy-0.13.1
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /home/tkloczko/rpmbuild/BUILD/openapi-0.7.0
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, freezegun-0.4.2, aspectlib-1.5.2, toolbox-0.5, rerunfailures-9.1.1, requests-mock-1.9.3, cov-2.12.1, flaky-3.7.0, benchmark-3.4.1, xdist-2.3.0, pylama-7.7.1, datadir-1.3.1, regressions-2.2.0, cases-3.6.3, xprocess-0.18.1, black-0.3.12, anyio-3.3.0, asyncio-0.15.1, trio-0.7.0, subtests-0.5.0, isort-2.0.0, hypothesis-6.14.6, mock-3.6.1, profiling-1.7.0, Faker-8.12.1, nose2pytest-1.0.8, pyfakefs-4.5.1, tornado-0.8.1, twisted-1.13.3
collected 223 items

tests/test_openapi.py .................................                                                                                                              [ 14%]
tests/test_schema_utils.py .........                                                                                                                                 [ 18%]
tests/test_spec_examples.py .........                                                                                                                                [ 22%]
tests/renderers/httpdomain/test_render_operation.py .............                                                                                                    [ 28%]
tests/renderers/httpdomain/test_render_parameter.py ..........................................                                                                       [ 47%]
tests/renderers/httpdomain/test_render_parameters.py .............                                                                                                   [ 53%]
tests/renderers/httpdomain/test_render_paths.py .........                                                                                                            [ 57%]
tests/renderers/httpdomain/test_render_request_body_example.py .........................                                                                             [ 68%]
tests/renderers/httpdomain/test_render_response.py ....................................                                                                              [ 84%]
tests/renderers/httpdomain/test_render_response_content.py ..............................                                                                            [ 98%]
tests/renderers/httpdomain/test_render_responses.py ....                                                                                                             [100%]

============================================================================= warnings summary =============================================================================
../../../../../usr/lib/python3.8/site-packages/_pytest/config/__init__.py:1183
  /usr/lib/python3.8/site-packages/_pytest/config/__init__.py:1183: PytestDeprecationWarning: The --strict option is deprecated, use --strict-markers instead.
    self.issue_config_time_warning(

-- Docs: https://docs.pytest.org/en/stable/warnings.html
====================================================================== 223 passed, 1 warning in 3.54s ======================================================================
pytest-xprocess reminder::Be sure to terminate the started process by running 'pytest --xkill' if you have not explicitly done so in your fixture with 'xprocess.getinfo(<process_name>).terminate()'.

BTW test suite. Looks like test suite needs only two files from OpenAPI-Specification: tests/OpenAPI-Specification/examples/v3.0/petstore.yaml and tests/OpenAPI-Specification/examples/v2.0/json/uber.json.
Is it not would be easier to just copy those two files into git repo instead linking submodule?

HTTP response codes - cannot be like '4XX', must be integer or start with an integer

Whilst the openapi spec allows HTTP codes for responses objects to be of type 2XX or 4XX (link) indicating a range of codes, this sphinx contrib seems unable to use those response codes appearing in a spec, with a warning:

(ERROR/3) HTTP status code must be an integer (e.g. 200) or start with an integer (e.g. 200 OK); <#text: '4XX'> is invalid

Not sure if the issue originates in the sphinxcontrib.openapi or in a dependency.

Way to reproduce: use an openapi.yaml spec with something like this in its paths:

paths:
  /myendpoint:
    post:
      requestBody:
      ...
      responses:
        '4XX':
          description: ...
          content:
             ...

Move to sphinx-contrib organization?

This is more of a request than a issue. I've noticed there are a few open PRs languishing against this project, but it's definitely useful to more than a few people. What's the possibility of moving this project to the sphinx-contrib on GitHub? I think it would be a good fit and, with your blessing of course, it could be a helpful way to spread the load assuming you simply don't have time to work on this at the moment.

Feel free to reach out to me via email (listed on my profile) if this is something you'd be interested in. I'd be happy to walk you through the steps necessary to do the migration (steps I'm working to document in the main Sphinx docs as we speak).

Consider adding the sphinx-extension GitHub topic

Just wanted to say you should consider adding the sphinx-extension topic, https://github.com/topics/sphinx-extension, to the repo so it is easier for others to find on the GitHub ecosystem. There are currently 94 other sphinx extensions that use that topic.

POST request specs missing in rendered docs

Running the provided example documentation at https://sphinxcontrib-openapi.readthedocs.io/#how-to-use

    post:
      summary: Create an Evidence
      description: |
        Creates a new evidence record in database.
      parameters:
        - name: evidence
          in: body
          schema:
            $ref: '#/definitions/Evidence'
      responses:
        201:
          description: An evidence.
          schema:
            $ref: '#/definitions/Evidence'

renders as:

I was also unable to get any description of the body in my own api specs using a parameter: block with in: body, or with the openapi 3.0 requestBody: block. Is there anything I need to configure in order for rendered docs to display a spec of the request body for POST requests? If this is intended let me know, I'm relatively new to writing openapi docs

Ignore vendor extensions in new renderer

The new renderer does not assume that there may be vendor extensions in OAS objects. I'm not sure what's going to happen, I can assume the renderer will either fail or render garbage when vendor extensions are met. We need to ensure they are ignored.

For this, I think we should implement some helper function, e.g. oas_iteritems(vendor_extensions=False) that can iterate via OAS objects with or without vendor extensions based on the parameter, and use that helper inside the renderer.

YAML 'merge' keys cause parsing failures

openapi/sphinxcontrib/openapi/utils.py

Line 39 in 547f645

_YamlOrderedLoader.add_constructor(

The constructor for DEFAULT_MAPPING_TAG linked above causes PyYAML to fail to support YAML 'merge keys'. Commenting out this constructor solves the problem, but presumably would cause other problems.

I've looked a bit into the PyYAML code but I'm not able to figure out what a potential solution might be.

'security' block is not loaded

Sphinx documentation generated from OpenAPI 3.0 doesn't contain information from security block. For example about required bearer token

TypeError: string indices must be integers

Traceback (most recent call last):
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/cmdline.py", line 296, in main
    app.build(opts.force_all, filenames)
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/application.py", line 333, in build
    self.builder.build_update()
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 265, in build
    self.doctreedir, self.app))
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 556, in update
    self._read_serial(docnames, app)
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 576, in _read_serial
    self.read_doc(docname, app)
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 684, in read_doc
    pub.publish()
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/core.py", line 217, in publish
    self.settings)
  File "/nix/store/6qss35pd3hkpfgx1p728r6rk3p58lcxd-python3.5-Sphinx-1.5.2/lib/python3.5/site-packages/sphinx/io.py", line 55, in read
    self.parse()
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/__init__.py", line 185, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 2745, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 326, in section
    self.new_subsection(title, lineno, messages)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 394, in new_subsection
    node=section_node, match_titles=True)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    node=node, match_titles=match_titles)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 2318, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 2330, in explicit_construct
    return method(self, expmatch)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 2073, in directive
    directive_class, match, type_name, option_presets)
  File "/nix/store/smcncpr5kq0kmjaagzawrnsrsq89990k-python3.5-docutils-0.13.1/lib/python3.5/site-packages/docutils/parsers/rst/states.py", line 2122, in run_directive
    result = directive_instance.run()
  File "/nix/store/9s7b3jgw3zdc65pp7cdvjrqx647g3hrk-python3.5-sphinxcontrib-openapi-0.3.0/lib/python3.5/site-packages/sphinxcontrib/openapi.py", line 183, in run
    for line in openapi2httpdomain(spec, **self.options):
  File "/nix/store/9s7b3jgw3zdc65pp7cdvjrqx647g3hrk-python3.5-sphinxcontrib-openapi-0.3.0/lib/python3.5/site-packages/sphinxcontrib/openapi.py", line 140, in openapi2httpdomain
    for endpoint in options.get('paths', spec['paths']):
TypeError: string indices must be integers

Using swagger file

Swagger {_swaggerInfo = Info {_infoTitle = "", _infoDescription = Nothing, _infoTermsOfService = Nothing, _infoContact = Nothing, _infoLicense = Nothing, _infoVersion = ""}, _swaggerHost = Nothing, _swaggerBasePath = Nothing, _swaggerSchemes = Nothing, _swaggerConsumes = MimeList {getMimeList = []}, _swaggerProduces = MimeList {getMimeList = []}, _swaggerPaths = fromList [("/projectNames",PathItem {_pathItemGet = Just (Operation {_operationTags = fromList [], _operationSummary = Nothing, _operationDescription = Nothing, _operationExternalDocs = Nothing, _operationOperationId = Nothing, _operationConsumes = Nothing, _operationProduces = Just (MimeList {getMimeList = [application/json]}), _operationParameters = [], _operationResponses = Responses {_responsesDefault = Nothing, _responsesResponses = fromList [(200,Inline (Response {_responseDescription = "", _responseSchema = Just (Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerArray, _paramSchemaFormat = Nothing, _paramSchemaItems = Just (SwaggerItemsObject (Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}))), _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})), _responseHeaders = fromList [], _responseExamples = Nothing}))]}, _operationSchemes = Nothing, _operationDeprecated = Nothing, _operationSecurity = []}), _pathItemPut = Nothing, _pathItemPost = Nothing, _pathItemDelete = Nothing, _pathItemOptions = Nothing, _pathItemHead = Nothing, _pathItemPatch = Nothing, _pathItemParameters = []}),("/project",PathItem {_pathItemGet = Just (Operation {_operationTags = fromList [], _operationSummary = Nothing, _operationDescription = Nothing, _operationExternalDocs = Nothing, _operationOperationId = Nothing, _operationConsumes = Nothing, _operationProduces = Just (MimeList {getMimeList = [application/json]}), _operationParameters = [], _operationResponses = Responses {_responsesDefault = Nothing, _responsesResponses = fromList [(200,Inline (Response {_responseDescription = "", _responseSchema = Just (Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerArray, _paramSchemaFormat = Nothing, _paramSchemaItems = Just (SwaggerItemsObject (Ref (Reference {getReference = "Project'"}))), _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})), _responseHeaders = fromList [], _responseExamples = Nothing}))]}, _operationSchemes = Nothing, _operationDeprecated = Nothing, _operationSecurity = []}), _pathItemPut = Nothing, _pathItemPost = Nothing, _pathItemDelete = Nothing, _pathItemOptions = Nothing, _pathItemHead = Nothing, _pathItemPatch = Nothing, _pathItemParameters = []}),("/project/{projectName}",PathItem {_pathItemGet = Just (Operation {_operationTags = fromList [], _operationSummary = Nothing, _operationDescription = Nothing, _operationExternalDocs = Nothing, _operationOperationId = Nothing, _operationConsumes = Nothing, _operationProduces = Just (MimeList {getMimeList = [application/json]}), _operationParameters = [Inline (Param {_paramName = "projectName", _paramDescription = Nothing, _paramRequired = Just True, _paramSchema = ParamOther (ParamOtherSchema {_paramOtherSchemaIn = ParamPath, _paramOtherSchemaAllowEmptyValue = Nothing, _paramOtherSchemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})})], _operationResponses = Responses {_responsesDefault = Nothing, _responsesResponses = fromList [(200,Inline (Response {_responseDescription = "", _responseSchema = Just (Ref (Reference {getReference = "Project'"})), _responseHeaders = fromList [], _responseExamples = Nothing})),(404,Inline (Response {_responseDescription = "`projectName` not found", _responseSchema = Nothing, _responseHeaders = fromList [], _responseExamples = Nothing}))]}, _operationSchemes = Nothing, _operationDeprecated = Nothing, _operationSecurity = []}), _pathItemPut = Nothing, _pathItemPost = Nothing, _pathItemDelete = Nothing, _pathItemOptions = Nothing, _pathItemHead = Nothing, _pathItemPatch = Nothing, _pathItemParameters = []}),("/projectWithJobsets",PathItem {_pathItemGet = Just (Operation {_operationTags = fromList [], _operationSummary = Nothing, _operationDescription = Nothing, _operationExternalDocs = Nothing, _operationOperationId = Nothing, _operationConsumes = Nothing, _operationProduces = Just (MimeList {getMimeList = [application/json]}), _operationParameters = [], _operationResponses = Responses {_responsesDefault = Nothing, _responsesResponses = fromList [(200,Inline (Response {_responseDescription = "", _responseSchema = Just (Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerArray, _paramSchemaFormat = Nothing, _paramSchemaItems = Just (SwaggerItemsObject (Ref (Reference {getReference = "ProjectWithJobsets"}))), _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})), _responseHeaders = fromList [], _responseExamples = Nothing}))]}, _operationSchemes = Nothing, _operationDeprecated = Nothing, _operationSecurity = []}), _pathItemPut = Nothing, _pathItemPost = Nothing, _pathItemDelete = Nothing, _pathItemOptions = Nothing, _pathItemHead = Nothing, _pathItemPatch = Nothing, _pathItemParameters = []}),("/protected",PathItem {_pathItemGet = Just (Operation {_operationTags = fromList [], _operationSummary = Nothing, _operationDescription = Nothing, _operationExternalDocs = Nothing, _operationOperationId = Nothing, _operationConsumes = Nothing, _operationProduces = Just (MimeList {getMimeList = [application/json]}), _operationParameters = [], _operationResponses = Responses {_responsesDefault = Nothing, _responsesResponses = fromList [(200,Inline (Response {_responseDescription = "", _responseSchema = Just (Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})), _responseHeaders = fromList [], _responseExamples = Nothing}))]}, _operationSchemes = Nothing, _operationDeprecated = Nothing, _operationSecurity = []}), _pathItemPut = Nothing, _pathItemPost = Nothing, _pathItemDelete = Nothing, _pathItemOptions = Nothing, _pathItemHead = Nothing, _pathItemPatch = Nothing, _pathItemParameters = []})], _swaggerDefinitions = fromList [("Project'",Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = ["projectName","projectDisplayname","projectEnabled","projectHidden","projectOwner"], _schemaAllOf = Nothing, _schemaProperties = fromList [("projectName",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectDisplayname",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectDescription",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectEnabled",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectHidden",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectOwner",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("projectHomepage",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}))], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerObject, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}),("ProjectWithJobsets",Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = ["projectWithJobsetsProject","projectWithJobsetsJobsets"], _schemaAllOf = Nothing, _schemaProperties = fromList [("projectWithJobsetsProject",Ref (Reference {getReference = "Project'"})),("projectWithJobsetsJobsets",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerArray, _paramSchemaFormat = Nothing, _paramSchemaItems = Just (SwaggerItemsObject (Ref (Reference {getReference = "Jobset'"}))), _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}))], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerObject, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}),("Jobset'",Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = ["jobsetName","jobsetProject","jobsetNixexprinput","jobsetNixexprpath","jobsetEnabled","jobsetEnableemail","jobsetHidden","jobsetEmailoverride","jobsetKeepnr","jobsetCheckinterval","jobsetSchedulingshares"], _schemaAllOf = Nothing, _schemaProperties = fromList [("jobsetName",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetProject",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetDescription",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetNixexprinput",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetNixexprpath",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetErrormsg",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetErrortime",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetLastcheckedtime",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetTriggertime",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetEnabled",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetEnableemail",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetHidden",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetEmailoverride",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetKeepnr",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetCheckinterval",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetSchedulingshares",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerInteger, _paramSchemaFormat = Just "int32", _paramSchemaItems = Nothing, _paramSchemaMaximum = Just 2.147483647e9, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Just -2.147483648e9, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})),("jobsetFetcherrormsg",Inline (Schema {_schemaTitle = Nothing, _schemaDescription = Nothing, _schemaRequired = [], _schemaAllOf = Nothing, _schemaProperties = fromList [], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerString, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}}))], _schemaAdditionalProperties = Nothing, _schemaDiscriminator = Nothing, _schemaReadOnly = Nothing, _schemaXml = Nothing, _schemaExternalDocs = Nothing, _schemaExample = Nothing, _schemaMaxProperties = Nothing, _schemaMinProperties = Nothing, _schemaParamSchema = ParamSchema {_paramSchemaDefault = Nothing, _paramSchemaType = SwaggerObject, _paramSchemaFormat = Nothing, _paramSchemaItems = Nothing, _paramSchemaMaximum = Nothing, _paramSchemaExclusiveMaximum = Nothing, _paramSchemaMinimum = Nothing, _paramSchemaExclusiveMinimum = Nothing, _paramSchemaMaxLength = Nothing, _paramSchemaMinLength = Nothing, _paramSchemaPattern = Nothing, _paramSchemaMaxItems = Nothing, _paramSchemaMinItems = Nothing, _paramSchemaUniqueItems = Nothing, _paramSchemaEnum = Nothing, _paramSchemaMultipleOf = Nothing}})], _swaggerParameters = fromList [], _swaggerResponses = fromList [], _swaggerSecurityDefinitions = fromList [], _swaggerSecurity = [], _swaggerTags = fromList [], _swaggerExternalDocs = Nothing}

Parsing fails when a response includes a header without a description

The exception looks like this:

Exception occurred:
  File "/usr/local/lib/python3.7/site-packages/sphinxcontrib/openapi/openapi20.py", line 75, in _httpresource
    for line in convert(header['description']).splitlines():
KeyError: 'description'

It appears to be because _httpresource blindly defererences header['description']. According to HeaderObject the description field is not required.

Release 0.6.0 with include and exclude

#56, which adds support for the include and exclude options, was merged about a month ago, but hasn't been released. The feature has been very useful in our project, so we've been working off of a GitHub pin of the commit. A point release (or patch, whatever works) would be appreciated. Thanks!

Build fails when resolving refs

openapi/sphinxcontrib/openapi/utils.py

Line 108 in 4f78db9

method.setdefault('parameters', [])

make html

...
reading sources... [ 45%] reference/monitor/api                             
Exception occurred:
  File "/usr/local/lib/python3.9/site-packages/sphinxcontrib/openapi/utils.py", line 108, in normalize_spec
    method.setdefault('parameters', [])
AttributeError: 'str' object has no attribute 'setdefault'
The full traceback has been saved in /var/folders/wh/w0_d38p56yz3fqwjj39tcnsw0000gp/T/sphinx-err-o1xngntb.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

reference/monitor/api.rst contains:

DMM Public APIs
===============

.. openapi:: /_static/api-specs/dmm-4.6/dmm.yaml
   :examples:

/_static/api-specs/dmm-4.6/dmm.yaml contains references like this one:

$ref: './drift_analyze.yaml#/components/schemas/driftAnalyzeRequest'

Where drift_analyze.yaml and other referenced files are in the same directory as dmm.yaml.

Markdown should be converted to reStructuredText

Multiple fields support CommonMark. We should convert that to rST, perhaps using something like reCommonMark

Full description of payload schema etc.

I just played with your sphinx extension (thanks!) and saw that the generated documentation covers only part of the OpenAPI specification. This can already be seen with the BatComputer example in the docs. The paths, parameters and responses are present in the docs, but the schema for the payload is missing, as are the bounds on the integer parameters etc., even though the definitions are all there.

Is this on purpose (the documentation will be high level) or is there just some more work needed to show everything (as with ReDoc)?

I wish to get the best of both worlds, that is the inline documentation, but with full detail.