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)