Skip to main content

A simple python program to generate OpenApi documentation by supplying request/response bodies.

Project description

InducOapi

ci PyPI version

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 git@github.com: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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

inducoapi-2.1.9.tar.gz (10.8 kB view hashes)

Uploaded Source

Built Distribution

inducoapi-2.1.9-py3-none-any.whl (11.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page