openapi-spec-tools 0.3.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.

OAS

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

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]).