1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
=====================
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.
.. code:: bash
pip install sphinxcontrib-openapi
How To Use?
===========
Consider you have the following OpenAPI spec saved at ``specs/openapi.yml``:
.. literalinclude:: specs/openapi.yml
:language: yaml
You can render it by using the ``openapi`` directive:
.. code:: restructuredtext
.. openapi:: specs/openapi.yml
and it will be rendered into something like:
.. openapi:: specs/openapi.yml
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:
.. code:: restructuredtext
.. 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`` or ``markdown``. If
not supplied, ReStructured Text is assumed.
``include``
A line separated list of regular expressions to filter the included openapi
spec by. For example:
.. code:: restructuredtext
.. 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:
.. code:: restructuredtext
.. openapi:: specs/openapi.yml
:exclude:
/evidence/{pk}
:encoding: utf-8
Would render ``/persons`` and ``/evidence`` endpoints, but not
``/evidence/{pk}`` endpoints
``methods``
A line separated list of http methods to filter included openapi
spec. For example:
.. code:: restructuredtext
.. 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:
.. code:: restructuredtext
.. openapi:: specs/openapi.yml
:http-methods-order:
head
get
Would render the ``head`` method, followed by the ``get`` method, followed by the rest of the methods in their declared ordered.
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification
.. _sphinxcontrib-httpdomain: https://sphinxcontrib-httpdomain.readthedocs.io/
.. _sphinxcontrib-redoc: https://sphinxcontrib-redoc.readthedocs.io/
|
