Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

inducoapi

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

inducoapi

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

  • 2.1.9
  • PyPI
  • Socket score

Maintainers
1

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)

Keywords

FAQs


Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc