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 :-) )