Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

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

Project description

pytest

InducOapi

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

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 openapi3.

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 OpenAPI spec 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

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 spec in a YAML file, just add --output openapi.yaml

From python

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
  • [ ] Generate resource definitions
  • [ ] Add support for headers
  • [ ] Add support for links
  • [ ] Add support for format

Project details


Download files

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

Files for inducoapi, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size inducoapi-1.0.0-py3-none-any.whl (10.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size inducoapi-1.0.0.tar.gz (9.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page