thewall89/inducoapi

A simple python module to generate OpenAPI Description Documents by supplying request/response bodies.

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 [email protected]: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 links (I don't think it is very useful)
• Add support for format (hard to infer)

inducoapi's Issues

Support generation of OpenApi Specification 3.1.0

https://spec.openapis.org/oas/v3.1.0

Add new parameter to select the OpenApi version. Defaults to 3.1.0 which is the latest.

Incompatibility with openapi-spec-validator-0.5.0

When running with openapi-spec-validator v0.5.0, the following occurs, so it looks like there have been some breaking changes.

> python3.10 -m inducoapi
Traceback (most recent call last):
  File "/usr/lib64/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib64/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/usr/lib/python3.10/site-packages/inducoapi/__main__.py", line 20, in <module>
    from openapi_spec_validator.exceptions import OpenAPIValidationError
ImportError: cannot import name 'OpenAPIValidationError' from 'openapi_spec_validator.exceptions' (/usr/lib/python3.10/site-packages/openapi_spec_validator/exceptions.py)

K

Publish PyPI package from GitHub actions

• Create PyPI project token for GitHub actions authentication
• Use release event to trigger package publishing
• Use poetry build and poetry publish

my-script

The entry point / script defined at https://github.com/TheWall89/inducoapi/blob/master/pyproject.toml#L21 is incorrect.

The result is:

$ my-script
Traceback (most recent call last):
  File "/usr/bin/my-script", line 33, in <module>
    sys.exit(load_entry_point('inducoapi==2.0.0', 'console_scripts', 'my-script')())
  File "/usr/bin/my-script", line 25, in importlib_load_entry_point
    return next(matches).load()
  File "/usr/lib64/python3.10/importlib/metadata/__init__.py", line 173, in load
    return functools.reduce(getattr, attrs, module)
AttributeError: module 'inducoapi' has no attribute 'main'