InducOapi
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.
Motivation
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
.
Installation
With pip
pip install inducoapi
git clone git@github.com:TheWall89/inducoapi.git
cd inducoapi
poetry install
To run unit-tests:
poetry run pytest
Usage
From CLI
inducoapi
provides its own command. You can simply execute it with
inducoapi
If 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 inducoapi
Help
inducoapi
provides its own help. Check it out with:
python -m inducoapi -h
Examples
Let'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 200
output
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.json
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
Let'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.json
output
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: manager
If you want to directly write the generated OpenAPI Description Documents to a YAML file, just
add --output openapi.yaml
From python
test_inducoapi.py provides usage examples of the module from python.
TODO list