A simple python program to generate OpenApi documentation by supplying request/response bodies.
Project description
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
With poetry
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
- Add support for request/response files in YAML
- Add support for
application/yaml
content - Customize title and version in info
- Package module
- Support for
$ref
in 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for inducoapi-2.1.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 19d6e3b2c5bdcb7630267b10329dd327dc3b354c059e6edfc5433a34d3c29403 |
|
MD5 | 83b5545b8f49e106fd1206c00067e31f |
|
BLAKE2b-256 | 1630ea9e214c3e0774e8e6934449ed61e152488e71a968e3359ed396292b6e6f |