Skip to main content

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

Project description

pytest PyPI version

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 sensible 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

Usage

From CLI

inducoapi provides its own help. Check it out with:

python -m inducoapi -h

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.0.0.tar.gz (10.6 kB view hashes)

Uploaded source

Built Distribution

inducoapi-2.0.0-py3-none-any.whl (11.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page