# InducOapi
[](https://github.com/TheWall89/inducoapi/actions/workflows/ci.yml)
[](https://badge.fury.io/py/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](https://github.com/p1c2u/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`
```shell script
pip install inducoapi
```
### With [poetry](https://python-poetry.org/)
```shell script
git clone git@github.com:TheWall89/inducoapi.git
cd inducoapi
poetry install
```
To run unit-tests:
```shell script
poetry run pytest
```
## Usage
### From CLI
`inducoapi` provides its own command. You can simply execute it with
```shell script
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:
```shell script
python -m inducoapi
```
#### Help
`inducoapi` provides its own help. Check it out with:
```shell script
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:
```shell script
python -m inducoapi GET /employees 200
```
<details><summary>output</summary>
```yaml
openapi: 3.0.0
info:
title: Generated by InducOapi
version: v1
paths:
/employees:
get:
responses:
200:
description: ''
```
</details>
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](examples).
```shell script
python -m inducoapi GET /employees 200 --response examples/employees.json
```
<details><summary>output</summary>
```yaml
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
```
</details>
Let's add a parameter to filter the employees by name.
```shell script
python -m inducoapi GET /employees 200 --response examples/employees.json --parameter name,query
```
<details><summary>output</summary>
```yaml
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: { }
```
</details>
Finally, let's try a POST request with both request and response examples.
```shell script
python -m inducoapi POST /employees 201 --request examples/new_employee_req.json --response examples/new_employee_resp.json
```
<details><summary>output</summary>
```yaml
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
```
</details>
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](tests/test_inducoapi.py) provides usage examples of the module from python.
## TODO list
- [x] Add support for request/response files in YAML
- [x] Add support for `application/yaml` content
- [x] Customize title and version in info
- [x] Package module
- [x] Support for `$ref` in response schemas
- [x] Add support for `parameters`
- [ ] ~~Add support for `links`~~ (I don't think it is very useful)
- [ ] ~~Add support for `format`~~ (hard to infer)
Raw data
{
"_id": null,
"home_page": "https://github.com/TheWall89/inducoapi",
"name": "inducoapi",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8.0",
"maintainer_email": null,
"keywords": "openapi, rest",
"author": "Matteo Pergolesi",
"author_email": "matpergo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d5/c6/9f4bc8e0cf096d29361b46ec2985402f812f9586addf2fba2b3eba4d50d3/inducoapi-2.1.8.tar.gz",
"platform": null,
"description": "# InducOapi\n\n[](https://github.com/TheWall89/inducoapi/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/inducoapi)\n\nA simple python module to generate OpenAPI Description Documents by supplying request/response bodies.\n\n*Contributions for new features, fixes or improvements are welcome. Feel free to send a pull request.*\n\n## Motivation\n\nSometimes you have a fully functioning HTTP service without OpenAPI documentation. At some point in time, others may\nneed to use your service. Writing the documentation by hand is a pain and can feel like an overwhelming job for complex\nservices.\n*inducoapi* helps you generate your OpenAPI Description Documents by taking as input request/response examples plus some\nother information.\n\nThe generated OpenAPI documentation is validated\nwith [openapi-spec-validator](https://github.com/p1c2u/openapi-spec-validator).\n\n*Warning*: This program also generates the `example` fields in OpenAPI schemas by default. If you have sensitive data in\nyour request/response files, disable this feature with `--no-example`.\n\n## Installation\n\n### With `pip`\n\n```shell script\npip install inducoapi\n```\n\n### With [poetry](https://python-poetry.org/)\n\n```shell script\ngit clone git@github.com:TheWall89/inducoapi.git\ncd inducoapi\npoetry install\n```\n\nTo run unit-tests:\n\n```shell script\npoetry run pytest\n```\n\n## Usage\n\n### From CLI\n\n`inducoapi` provides its own command. You can simply execute it with\n\n```shell script\ninducoapi\n```\n\nIf you get a `command not found` error, try to activate your virtualenv or run `poetry shell` first.\n\nYou can also run `inducoapi` in the classic way:\n\n```shell script\npython -m inducoapi\n```\n\n#### Help\n\n`inducoapi` provides its own help. Check it out with:\n\n```shell script\npython -m inducoapi -h\n```\n\n#### Examples\n\nLet's consider a simple case: you have an HTTP service managing employees. We want to generate the OpenAPI Description\nDocument for a GET on all the employees, returning a 200 status code:\n\n```shell script\npython -m inducoapi GET /employees 200\n```\n\n<details><summary>output</summary>\n\n```yaml\nopenapi: 3.0.0\ninfo:\n title: Generated by InducOapi\n version: v1\npaths:\n /employees:\n get:\n responses:\n 200:\n description: ''\n```\n\n</details>\n\nNow, a GET request with an empty response is not quite useful. Let's add an argument with a JSON file containing a\nresponse example. Input examples can be found in [examples](examples).\n\n```shell script\npython -m inducoapi GET /employees 200 --response examples/employees.json\n```\n\n<details><summary>output</summary>\n\n```yaml\nopenapi: 3.0.0\ninfo:\n title: Generated by InducOapi\n version: v1\npaths:\n /employees:\n get:\n responses:\n 200:\n description: ''\n content:\n application/json:\n schema:\n type: array\n items:\n type: object\n properties:\n id:\n type: integer\n example: 1\n name:\n type: string\n example: Dwight Schrute\n role:\n type: string\n example: salesman\n```\n\n</details>\n\nLet's add a parameter to filter the employees by name.\n\n```shell script\npython -m inducoapi GET /employees 200 --response examples/employees.json --parameter name,query \n```\n\n<details><summary>output</summary>\n\n```yaml\nopenapi: 3.0.0\ninfo:\n title: Generated by InducOapi\n version: v1\npaths:\n /employees:\n get:\n responses:\n '200':\n description: ''\n content:\n application/json:\n schema:\n type: array\n items:\n type: object\n properties:\n id:\n type: integer\n example: 1\n name:\n type: string\n example: Dwight Schrute\n role:\n type: string\n example: salesman\n parameters:\n - name: name\n in: query\n required: false\n description: ''\n schema: { }\n```\n\n</details>\n\nFinally, let's try a POST request with both request and response examples.\n\n```shell script\npython -m inducoapi POST /employees 201 --request examples/new_employee_req.json --response examples/new_employee_resp.json\n```\n\n<details><summary>output</summary>\n\n```yaml\nopenapi: 3.0.0\ninfo:\n title: Generated by InducOapi\n version: v1\npaths:\n /employees:\n post:\n requestBody:\n content:\n application/json:\n schema:\n type: object\n properties:\n name:\n type: string\n example: Michael Scott\n role:\n type: string\n example: manager\n responses:\n 201:\n description: ''\n content:\n application/json:\n schema:\n type: object\n properties:\n id:\n type: integer\n example: 4\n name:\n type: string\n example: Michael Scott\n role:\n type: string\n example: manager\n```\n\n</details>\n\nIf you want to directly write the generated OpenAPI Description Documents to a YAML file, just\nadd `--output openapi.yaml`\n\n### From python\n\n[test_inducoapi.py](tests/test_inducoapi.py) provides usage examples of the module from python.\n\n## TODO list\n\n- [x] Add support for request/response files in YAML\n- [x] Add support for `application/yaml` content\n- [x] Customize title and version in info\n- [x] Package module\n- [x] Support for `$ref` in response schemas\n- [x] Add support for `parameters`\n- [ ] ~~Add support for `links`~~ (I don't think it is very useful)\n- [ ] ~~Add support for `format`~~ (hard to infer)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A simple python program to generate OpenApi documentation by supplying request/response bodies.",
"version": "2.1.8",
"project_urls": {
"Homepage": "https://github.com/TheWall89/inducoapi",
"Repository": "https://github.com/TheWall89/inducoapi"
},
"split_keywords": [
"openapi",
" rest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "956c7de1dda30e8c9df65ff0a214a2a2b96a3c6172cb3384fc55339d2e9848f6",
"md5": "3951ba0447415e3266d70f0d2e41fd7c",
"sha256": "5b59aff6951fd926582b12c30b96afb70744651d1d895e6a056d6c0e61055c3f"
},
"downloads": -1,
"filename": "inducoapi-2.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3951ba0447415e3266d70f0d2e41fd7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8.0",
"size": 11493,
"upload_time": "2024-07-07T09:59:09",
"upload_time_iso_8601": "2024-07-07T09:59:09.248481Z",
"url": "https://files.pythonhosted.org/packages/95/6c/7de1dda30e8c9df65ff0a214a2a2b96a3c6172cb3384fc55339d2e9848f6/inducoapi-2.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5c69f4bc8e0cf096d29361b46ec2985402f812f9586addf2fba2b3eba4d50d3",
"md5": "af73d17c0d9966ba6af57f571b9c6d06",
"sha256": "c2960067d8450746bda8fbc884c09585be3db90beed94136e9ba5ff103d135e2"
},
"downloads": -1,
"filename": "inducoapi-2.1.8.tar.gz",
"has_sig": false,
"md5_digest": "af73d17c0d9966ba6af57f571b9c6d06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8.0",
"size": 10763,
"upload_time": "2024-07-07T09:59:10",
"upload_time_iso_8601": "2024-07-07T09:59:10.320049Z",
"url": "https://files.pythonhosted.org/packages/d5/c6/9f4bc8e0cf096d29361b46ec2985402f812f9586addf2fba2b3eba4d50d3/inducoapi-2.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-07 09:59:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TheWall89",
"github_project": "inducoapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "inducoapi"
}
JSON
