Metadata-Version: 2.3
Name: openapi-spec-tools
Version: 0.3.0
Summary: OpenAPI specification tools for analyzing, updating, and generating a CLI.
Author: Rick Porter
Author-email: rickwporter@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: rich (>=14.0.0,<15.0.0)
Requires-Dist: typer (>=0.16.0,<0.17.0)
Description-Content-Type: text/markdown

# 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](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](LAYOUT.md) has more details about the layout file, and the [CLI_GEN.md](CLI_GEN.md) has more info about CLI generation.

Turn a simple layout like:
```YAML
main:
  description: Manage pets
  operations:
    - name: add
      operationId: createPets
```

Into code that produces a CLI that has commands like:
```terminal
% 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](https://github.com/OpenAPITools/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](https://openapi-generator.tech/docs/usage#generate).

## Contributing

The [DEVELOPMENT.md](DEVELOPMENT.md) has more information about getting setup as a developer.

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

