# 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/88/64/03489cb79f1e5e929d530d285d699ee16f235216f2e34e32382ad2dfb494/inducoapi-2.1.5.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.5",
"project_urls": {
"Homepage": "https://github.com/TheWall89/inducoapi",
"Repository": "https://github.com/TheWall89/inducoapi"
},
"split_keywords": [
"openapi",
" rest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b847b8dfa4f5409ed4eeb2ed4e7e9fe4dd52c651355d83eb973bd6947677a0db",
"md5": "8766f585424d6ca1dc21f9677bb7efd5",
"sha256": "cfaec79ccd0d36518826ae549f2834ed781de8d1ad90dbda54f9feae91f6717e"
},
"downloads": -1,
"filename": "inducoapi-2.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8766f585424d6ca1dc21f9677bb7efd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8.0",
"size": 11491,
"upload_time": "2024-04-27T20:50:31",
"upload_time_iso_8601": "2024-04-27T20:50:31.830797Z",
"url": "https://files.pythonhosted.org/packages/b8/47/b8dfa4f5409ed4eeb2ed4e7e9fe4dd52c651355d83eb973bd6947677a0db/inducoapi-2.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "886403489cb79f1e5e929d530d285d699ee16f235216f2e34e32382ad2dfb494",
"md5": "8a43f86b10871033b2a437199523e117",
"sha256": "635af583d0448087a07a3683858f46dbfdd81741a3c11bda18a96bcb2fdaec76"
},
"downloads": -1,
"filename": "inducoapi-2.1.5.tar.gz",
"has_sig": false,
"md5_digest": "8a43f86b10871033b2a437199523e117",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8.0",
"size": 10766,
"upload_time": "2024-04-27T20:50:33",
"upload_time_iso_8601": "2024-04-27T20:50:33.849362Z",
"url": "https://files.pythonhosted.org/packages/88/64/03489cb79f1e5e929d530d285d699ee16f235216f2e34e32382ad2dfb494/inducoapi-2.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 20:50:33",
"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
