Sanitizes unused definitions from OpenAPI specification files(YAML and JSON)
Project description
openapi-spec-sanitizer
A Sanitizer for OpenAPI YAML, or JSON, spec files
Description
Offers a CLI, or simple API, to detect, report, and, optionally, fix unused components in OpenAPI specifications
- Detects unused, or undefined, components in Swagger (2.0) and OpenAPI (3.*) (YAML or json) specifications
- It can sanitize discovered unused components, either by:
- deleting the component
- or adding a new tag to the component
- Sanitised YAML, or json, is stored to file
- OpenAPI/Swagger Spec files can be loaded from URI or file
- It always tries not to overwrite existing files(yay!)
- It detects (unsupported so far) remote references and politely gives up
This package was written with a single purpose in mind, and makes no claims other than proving quite useful for that particular purpose.
Hopefully it will find a more general use.
TODO
It doesn't do many things, but of note it might be useful to(most-likely first):
Add support for JSON-format Specification- Add support for remote references, which depends on:
- Add support for multiple files
- Add support for caching remote (url) specifications to file
Author
David Turland, david@turland.org
Install
From PyPi:
pip install openapi-spec-sanitizer
From source:
python3 -m pip install
# or
python3 -m pip install --user
Usage
usage: openapi_spec_sanitizer [-h] [-c CACHEDIR] [-s] [-t TAG | -r]
[-o OUTPUT] [-l] [-v] [-g] [--version]
filename
Sanitize OpenAPI.
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
output file name for sanitized YAML
-l, --lax YAML, or JSON, syntax warnings are tolerable
-v, --verbose
-g, --debug
--version show the version number and exit
YAML, or JSON, Loading Options:
filename OpenAPI specification: file path or url (YAML, or JSON)
Sanitizing Options:
-s, --sanitize Attempt to sanitize spec file (default False)
-t TAG, --tag TAG sanitize mode is to tag component
-r, --remove Sanitize mode is to remove component
Examples
Testing for Unused and Undefined Component detection
openapi_spec_sanitizer tests/simple.yaml -l
------------------------ Analyzer Report ----------------
Undefined components
'/components/requestBodies/requestBodyMissingRequired'
'/components/schemas/schemaPlainMissingUnused'
Uunused components
path: /components/requestBodies/requestBodyAUnused
Type: Component, path: /components/requestBodies/requestBodyAUnused, line: 15, is component? True, is declared? True, is required? False
----------------------- ~Analyzer Report ----------------
Sanitizing Unused components
Here we have an OpenAPI spec with an unused component,/components/requestBodies/requestBodyAUnused
openapi: 3.0.0
paths:
/wibble:
post:
summary: wobble
requestBody:
application/json:
schema:
type: "string"
responses:
'201':
$ref: '#/components/responses/responseA'
components:
parameters:
requestBodies:
requestBodyAUnused:
description: requestBodyAUnused description
required: true
content:
application/json:
schema:
type: "string"
responses:
responseA:
description: responseA
headers:
Floob:
schema:
type: "string"
Running openapi_spec_sanitizer
with -s
to sanitize
NOTE the default mode is to tag unused components with unused
openapi_spec_sanitizer.exe tests/simple_unused.yaml -s
...
Main: dumping sanitized YAML to tests/simple_unused.san.yaml
------------------------ Analyzer Report ----------------
Uunused components
path: /components/requestBodies/requestBodyAUnused
Type: Component, path: /components/requestBodies/requestBodyAUnused, line: 17, is component? True, is declared? True, is required? False
----------------------- ~Analyzer Report ----------------
Yields this sanitized YAML:
note the unused component tagged with unused
openapi: 3.0.0
paths:
/wibble:
post:
summary: wobble
requestBody:
application/json:
schema:
type: string
responses:
'201':
$ref: '#/components/responses/responseA'
components:
parameters: null
requestBodies:
requestBodyAUnused:
description: requestBodyAUnused description
required: true
content:
application/json:
schema:
type: string
unused: true
responses:
responseA:
description: responseA
headers:
Floob:
schema:
type: string
Tests
Basic Testing
pytest
OpenBanking Specification Tests
Tests some of the OpenAPI spec files from the OpenBanking Official Open Banking UK API Standards
And yes (as of 14/2/23) there are unused components...
NOTE:
- These tests are not run as part of python setuptools
- Remote spec files are cached once and used locally
pytest tests/openbanking
Attributions
OpenAPI Initiative OpenAPI-Specification - A snapshot of one of their sample OpenAPI spec files,api-with-examples.yaml, is stored in this repo, and is used in one of the unit tests (It passes BTW :-) )
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for openapi-spec-sanitizer-0.1.13.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0d92a208ac34c0383452235430c38ef3ab6ddd7d5a3f151bcb3678fa99cfa225 |
|
MD5 | 5684e1fdf7bb108c7d26273505f6a463 |
|
BLAKE2b-256 | 2a32036144d62bd64cff43cb36dac5c01eb41119df1e584a933c89672af5a5de |
Hashes for openapi_spec_sanitizer-0.1.13-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d1d6544a14c6e6bb7ed5e20045815b94c23c06d0bd4a2f1dc7c837efd34fb349 |
|
MD5 | 07343f2631f5bceca92051340d4c9406 |
|
BLAKE2b-256 | 61a13758a7cd7f10c517d4141872dcfc0ca45ee215be8b7de5696b090ba15933 |