openapi-spec-tools 0.5.0

OpenAPI specification tools for analyzing, updating, and generating a CLI.

openapi-spec-tools

Welcome to OpenAPI specification (OAS) tools!

This is a collection of tools for using OpenAPI specifications. The OpenAPI community has a plethora of tools, and this is intended to supplement those. The tools here provide functionality that has not been readily available elsewhere.

Getting started

The project has been published to PyPi, so you should be able to install it with something like one of the following (depending on how you do Python package management):

% pip install openapi-spec-tools
% poetry add openapi-spec-tools

Generally, there are two intended ways to utilize this package:

• Use oas and cli-gen as CLI tools to perform actions
• Use the code in the Python modules for your own purpose

The sections below provide a brief description with links to more examples and details.

OAS

The oas script provides a tool for analyzing and modifying an OpenAPI spec. See OAS.md for more info.

Here's a trivial example:

(.env) % oas analyze models list pet.yaml 
Found 3 models:
    Error
    Pet
    Pets
(.env) % oas analyze models ops pet.yaml Pet
Found Pet is used by 3 operations:
    createPets
    listPets
    showPetById
(.env) % 

CLI Generation

The cli-gen tool allows users to create a user-friendly CLI using the OpenAPI spec and a layout file. The layout file provides the CLI structure and refers to the OpenAPI spec for details of operations. LAYOUT.md has more details about the layout file, and the CLI_GEN.md has more info about CLI generation.

Turn a simple layout like:

main:
  description: Manage pets
  operations:
    - name: add
      operationId: createPets

Into code that produces a CLI that has commands like:

% pets add --help
                                                                                                                                                        
 Usage: pets add [OPTIONS]                                             

 Create a pet
 
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --id                 INTEGER                                                                                                                         │
│ --name               TEXT                                                                                                                            │
│ --tag                TEXT                                                                                                                            │
│ --owner              TEXT                                                                                                                            │
│ --api-host           TEXT                              API host address [env var: API_HOST]                                                          │
│ --api-key            TEXT                              API key for authentication [env var: API_KEY]                                                 │
│ --api-timeout        INTEGER                           API request timeout in seconds for a single request [env var: API_TIMEOUT] [default: 5]       │
│ --log                [critical|error|warn|info|debug]  Log level [env var: LOG_LEVEL] [default: warn]                                                │
│ --format             [table|json|yaml]                 Output format style [env var: OUTPUT_FORMAT] [default: table]                                 │
│ --style              [none|bold|all]                   Style for output [env var: OUTPUT_STYLE] [default: all]                                       │
│ --help                                                 Show this message and exit.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
% 

See the examples in examples/ for some more complete works.

client.mk

The client.mk file is an example of a Makefile to invoke the OpenAPI generator via a container. The file can be copied/modified to be invoked with an OpenAPI specfication (other than openapi.yaml) and a real package name. For a more complete list of generator options, look at the OpenAPI generator usage documentation.

Contributing

The DEVELOPMENT.md has more information about getting setup as a developer.

The TODO.md has some ideas where this project can be improved and expanded -- please add your ideas here, or email Rick directly ([e-mail]).