A simple python module to generate OpenAPI Description Documents by supplying request/response bodies.
Contributions for new features, fixes or improvements are welcome. Feel free to send a pull request.
Sometimes you have a fully functioning HTTP service without OpenAPI documentation. At some point in time, others may need to use your service. Writing the documentation by hand is a pain and can feel like an overwhelming job for complex services. inducoapi helps you generate your OpenAPI Description Documents by taking as input request/response examples plus some other information.
The generated OpenAPI documentation is validated with openapi-spec-validator.
Warning: This program also generates the example fields in OpenAPI schemas by default. If you have sensitive data in
your request/response files, disable this feature with --no-example.
pip install inducoapiWith poetry
git clone [email protected]:TheWall89/inducoapi.git
cd inducoapi
poetry installTo run unit-tests:
poetry run pytestinducoapi provides its own command. You can simply execute it with
inducoapiIf you get a command not found error, try to activate your virtualenv or run poetry shell first.
You can also run inducoapi in the classic way:
python -m inducoapiinducoapi provides its own help. Check it out with:
python -m inducoapi -hLet's consider a simple case: you have an HTTP service managing employees. We want to generate the OpenAPI Description Document for a GET on all the employees, returning a 200 status code:
python -m inducoapi GET /employees 200output
openapi: 3.0.0
info:
title: Generated by InducOapi
version: v1
paths:
/employees:
get:
responses:
200:
description: ''Now, a GET request with an empty response is not quite useful. Let's add an argument with a JSON file containing a response example. Input examples can be found in examples.
python -m inducoapi GET /employees 200 --response examples/employees.jsonoutput
openapi: 3.0.0
info:
title: Generated by InducOapi
version: v1
paths:
/employees:
get:
responses:
200:
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Dwight Schrute
role:
type: string
example: salesmanLet's add a parameter to filter the employees by name.
python -m inducoapi GET /employees 200 --response examples/employees.json --parameter name,query output
openapi: 3.0.0
info:
title: Generated by InducOapi
version: v1
paths:
/employees:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Dwight Schrute
role:
type: string
example: salesman
parameters:
- name: name
in: query
required: false
description: ''
schema: { }Finally, let's try a POST request with both request and response examples.
python -m inducoapi POST /employees 201 --request examples/new_employee_req.json --response examples/new_employee_resp.jsonoutput
openapi: 3.0.0
info:
title: Generated by InducOapi
version: v1
paths:
/employees:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Michael Scott
role:
type: string
example: manager
responses:
201:
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: Michael Scott
role:
type: string
example: managerIf you want to directly write the generated OpenAPI Description Documents to a YAML file, just
add --output openapi.yaml
test_inducoapi.py provides usage examples of the module from python.
- Add support for request/response files in YAML
- Add support for
application/yamlcontent - Customize title and version in info
- Package module
- Support for
$refin response schemas - Add support for
parameters -
Add support for(I don't think it is very useful)links -
Add support for(hard to infer)format
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent