sphinxcontrib-openapi
Hint
Check out sphinxcontrib-redoc if you are interested in separate three-panel OpenAPI spec rendering.
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.
pip install sphinxcontrib-openapi
How To Use?
Consider you have the following OpenAPI spec saved at specs/openapi.yml
:
swagger: "2.0"
info:
title: Batcomputer API
version: "1.0.0"
host: api.batcomputer.com
paths:
/persons:
get:
summary: List Persons
description: |
Retrieves a list of all persons on file in the bat computer.
responses:
200:
description: An array of Persons
schema:
type: array
items:
$ref: '#/definitions/Person'
/evidence:
get:
summary: List Evidence
description: |
Retrieves a list of evidence ever found by world's greatest
detective and his family.
parameters:
- name: marker
in: query
type: integer
minimum: -1
default: -1
format: int64
required: false
description: |
The id of the last seen evidence. It's used for pagination purpose
by returning 'limit' number of evidence after this one.
- name: limit
in: query
type: integer
format: int32
minimum: 1
maximum: 1000
default: 20
required: false
description: |
The maximum number of evidence to be returned by the query.
responses:
200:
description: An array of evidence.
schema:
type: array
items:
$ref: '#/definitions/Evidence'
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'
/evidence/{id}:
get:
summary: Show Requested Evidence
description: |
Queries and returns an evidence with a passed ID.
parameters:
- name: id
in: path
type: integer
format: int64
required: true
description: |
A unique evidence identifier to query.
- name: If-None-Match
in: header
type: string
description: |
Executes a request only if passed ETag doesn't equal to current
resource one (i.e. resource has been changed).
responses:
200:
description: An evidence.
schema:
$ref: '#/definitions/Evidence'
headers:
ETag:
description: |
Entity tag is part of HTTP provided for web cache validation
problem, but also used for optimistic concurrency control.
type: string
404:
description: Evidence not found.
schema:
$ref: '#/definitions/Error'
definitions:
Evidence:
type: object
properties:
id:
type: integer
format: int64
description: A unique evidence identifier.
case:
type: string
description: A case when the evidence is found.
data:
type: string
format: binary
description: An evidence itself.
Error:
type: object
properties:
code:
type: string
description: A uniqe identifier of error.
message:
type: string
description: A human readable error message.
Person:
type: object
properties:
id:
type: integer
format: int64
description: Unique ID for a person
name:
type: string
description: Name of a person
You can render it by using the openapi
directive:
.. openapi:: specs/openapi.yml
and it will be rendered into something like:
- GET /persons
List Persons
Retrieves a list of all persons on file in the bat computer.
- Status Codes:
200 OK – An array of Persons
- Response JSON Object:
[].id (integer) – Unique ID for a person
[].name (string) – Name of a person
- GET /evidence
List Evidence
Retrieves a list of evidence ever found by world’s greatest detective and his family.
- Query Parameters:
marker (integer) – The id of the last seen evidence. It’s used for pagination purpose by returning ‘limit’ number of evidence after this one.
limit (integer) – The maximum number of evidence to be returned by the query.
- Status Codes:
200 OK – An array of evidence.
- Response JSON Object:
[].case (string) – A case when the evidence is found.
[].data (string) – An evidence itself.
[].id (integer) – A unique evidence identifier.
- POST /evidence
Create an Evidence
Creates a new evidence record in database.
- Request JSON Object:
case (string) – A case when the evidence is found.
data (string) – An evidence itself.
id (integer) – A unique evidence identifier.
- Status Codes:
201 Created – An evidence.
- Response JSON Object:
case (string) – A case when the evidence is found.
data (string) – An evidence itself.
id (integer) – A unique evidence identifier.
- GET /evidence/{id}
Show Requested Evidence
Queries and returns an evidence with a passed ID.
- Parameters:
id (integer) – A unique evidence identifier to query.
- Status Codes:
200 OK – An evidence.
404 Not Found – Evidence not found.
- Request Headers:
If-None-Match – Executes a request only if passed ETag doesn’t equal to current resource one (i.e. resource has been changed).
- Response Headers:
ETag – Entity tag is part of HTTP provided for web cache validation problem, but also used for optimistic concurrency control.
- Response JSON Object:
case (string) – A case when the evidence is found.
data (string) – An evidence itself.
id (integer) – A unique evidence identifier.
Options
The openapi
directive supports the following options:
encoding
Encoding to be used to read an OpenAPI spec. If not passed, Sphinx’s source encoding will be used.
paths
A comma separated list of paths to filter the included OpenAPI spec by. For example:
.. openapi:: specs/openapi.yml :paths: /persons /evidence :encoding: utf-8
Would only render the endpoints at
/persons
and/evidence
, ignoring all others.examples
If passed, both request and response examples will be rendered. Please note, if examples are not provided in a spec, they will be generated by internal logic based on a corresponding schema.
group
If passed, paths will be grouped by tags. If a path has no tag assigned, it will be grouped in a
default
group.format
The format of text in the spec, either
rst
ormarkdown
. If not supplied, ReStructured Text is assumed.include
A line separated list of regular expressions to filter the included openapi spec by. For example:
.. openapi:: specs/openapi.yml :include: /evid.* :encoding: utf-8
Would render the endpoints at
/evidence
and/evidence/{pk}
exclude
A line separated list of regular expressions to filter the included openapi spec by (excluding matches). For example:
.. openapi:: specs/openapi.yml :exclude: /evidence/{pk} :encoding: utf-8
Would render
/persons
and/evidence
endpoints, but not/evidence/{pk}
endpointsmethods
A line separated list of http methods to filter included openapi spec. For example:
.. openapi:: specs/openapi.yml :methods: get post put :encoding: utf-8
Would render paths with get, post or put method
exclude
, include
and paths
can also be used together (exclude
taking precedence over include
and paths
)
http-methods-order
A whitespace delimited list of HTTP methods to render first. For example:
.. openapi:: specs/openapi.yml :http-methods-order: head get
Would render the
head
method, followed by theget
method, followed by the rest of the methods in their declared ordered.