InducOapi
A simple python module to generate OpenAPI Description Documents by supplying request/response bodies.
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 openapi3.
Warning: This program also generates the example fields in OpenAPI schemas by default.
If you have sensible 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
Usage
From CLI
inducoapi provides its own help. Check it out with:
python -m inducoapi -h
Let's consider a simple case: you have an HTTP service managing employees. We want to generate OpenAPI spec 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
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 spec in 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/yamlcontent - Customize title and version in info
- Package module
- Support for
$refin response schemas - Add support for
headers - Add support for
links - Add support for
format
Metadata
Release files for inducoapi 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| inducoapi-1.1.0.tar.gz | 9.9 kB | Without provenance | Details for inducoapi-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| inducoapi-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for inducoapi-1.1.0-py3-none-any.whl |
Total release size: 20.6 kB
Release files / inducoapi-1.1.0.tar.gz
| Download URL | inducoapi-1.1.0.tar.gz |
|---|---|
| Size | 9.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f5e46665f21299fe2ac9c9c0aae563db31ca5e56ba44c166292ce92476a1085
|
|
BLAKE2b-256 checksum How to use checksums |
b0c51a2e4539335852e3c8591aedfa0e29269e34fd1a4b34f7e7a90e02b416fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.1.4 CPython/3.6.10 Linux/5.10.13-zen1-1-zen
|
Release files / inducoapi-1.1.0-py3-none-any.whl
| Download URL | inducoapi-1.1.0-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
44b1835cd8809f7957cdc74a32ef15b6c77e677f1023ea07cb6e94a0c55e7554
|
|
BLAKE2b-256 checksum How to use checksums |
bb25928034f9e3d50ee50834933127980c75356bd20d3393f17f47d3c1b6b31e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.1.4 CPython/3.6.10 Linux/5.10.13-zen1-1-zen
|
Security for inducoapi 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.