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.
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/yaml
content - Customize title and version in info
- Package module
- Support for
$ref
in response schemas - Add support for
headers
- Add support for
links
- Add support for
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-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 44b1835cd8809f7957cdc74a32ef15b6c77e677f1023ea07cb6e94a0c55e7554 |
|
MD5 | 24dab998ff23a26d6f39949f1e0101cb |
|
BLAKE2b-256 | bb25928034f9e3d50ee50834933127980c75356bd20d3393f17f47d3c1b6b31e |