/static_swagger-ui

Produce a static page similar to what Swagger-UI produced. (faster, cleaner, no js bloatware)

Primary LanguagePythonApache License 2.0Apache-2.0

Static Swagger-UI

This script takes the same JSON file that Swagger-UI requires and builds a static web page with a nearly identical appearance to what is produced by Swagger-UI.

Benefits:

  • Browser does not need to download and parse a large JSON file
  • Browser does not need to keep the large file in memory
  • No wait for initial download and rendering "Loading..."
  • No wait for expanding sections
  • No additional processing to build sections before expanding
  • Browser does not need to handle heavy javascript processing
  • No dependencies outside of base python
  • Written for Debian Devs; easily used in any project deployment
  • Works as a python module

This script does not implement all features of the javascript version and instead focuses on providing a useful manual.

Development Status

Unless interest develops, I do not intend to actively maintain this project.

Testing

Local environment variables:

export SWAGGER_DST='swaggerui.html'
export SWAGGER_SRC='swagger.v1.json'

Get JSON:

python -c 'import build; build.download_json()'

Build:

./build.py

Debian Dev

This script exists to avoid packaging an excessive and insane number of build dependencies for node-swagger-ui. The additional benefits are just happy side effects.

To add this to your package:

  • debian/control: Build-Depends: python
  • wget https://raw.githubusercontent.com/MTecknology/static_swagger-ui/master/build.py -O debian/helpers/swagger_build.py
  • sed -i '/REMOVE/,/REMOVE/d' debian/helpers/swagger_build.py
  • d/rules: override_dh_auto_build: [...]

Example d/rules:

override_dh_auto_build:
        python debian/helpers/swagger_build.py
        # or..
        SWAGGER_SRC='/.../swagger.v1.json' SWAGGER_DST=swag.html python debian/helpers/swagger_build.py
        go install -v -p 4 \
                -buildmode=pie \
                -pkgdir="$(GOPATH)" [...]

Note: The license on this source is now Apache-2.0 which only requires attribution in source. (i.e. maintain the file header; that's it)

Module

This script can be used in python as a module.

An overly-verbose example:

import build as swag
tmp = 'swag.json'
output = 'swagger-static.html'
swag.download_json('http://domain.tld/swagger.v1.json', tmp)
json_data = swag.read_json(tmp)
rendered_page = swag.render_page(json_data)
write_successe = swag.write_static(rendered_page, outpt)
if not write_success:
    print ('oops...')

More simply:

import build as swag
src = '/.../swagger.v1.json'
page = swag.render_page(swag.read_json(src))

Shell

Of course, it's also possible to run it from a shell:

# download
SWAGGER_URL=http://domain.tld/swagger.v1.json SWAGGER_DST=swagger.v1.json python build.py
# or build
SWAGGER_SRC=swagger.v1.json NODL=1 SWAGGER_DST=public/swagger.html python build.py
# or both
SWAGGER_URL=http://domain.tld/swagger.v1.json SWAGGER_DST=swag.html python build.py

Demo

Execution:

python build.py

Output:

Environment Variables:

  • SWAGGER_SRC: JSON input file (default: swagger.html)
  • SWAGGER_DST: Static HTML file; Download destination location (default: swagger.v1.json)
  • SWAGGER_URL: URL to download JSON file from (default: https://try.gitea.io/swagger.v1.json)
  • NODL: Skip download check; or see above sed command (default: <unset>)