Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

essentials-openapi

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

essentials-openapi

Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.

  • 1.0.9
  • PyPI
  • Socket score

Maintainers
1

Build pypi versions license codecov

essentials-openapi

Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML, and to generate other kinds of documents from OpenAPI Documentation files.

pip install essentials-openapi

To install with dependencies to generate other kinds of artifacts from source OpenAPI Documentation files:

pip install essentials-openapi[full]

Usage

This library has been originally created to implement generation of OpenAPI Documentation in the BlackSheep web framework. However, this package is abstracted from that web framework and can be reused for other applications. Today this library also offers functions to generate documentation from source OpenAPI Documentation files.

Features to generate artifacts from Open API Documentation

These require the full package: install it using pip install essentials-openapi[full].

To generate output for MkDocs and PyMdown extentions:

oad gen-docs -s example1-openapi.json -d output.md

Example MkDocs documentation

Example of MkDocs documentation generated using Neoteroi/mkdocs-plugins.


To generate a PlantUML class diagram of the components schemas:

oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_SCHEMAS"

Example schemas

Example of PlantUML diagram generated from components schemas.


To generate a PlantUML class diagram with an overview of API endpoints:

oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"

Example api overview

Example of PlantUML diagram generated from path items.

Goals

  • Provide an API to generate OpenAPI Documentation files.
  • Providing functions to handle OpenAPI Documentation, like those to generate other kinds of documentation from source OpenAPI Documentation files.
  • Support enough features to be useful for the most common API scenarios, especially for OAD files that are generated automatically from web frameworks.

Non-Goals

  • To implement the whole OAD Specification.
  • For the features that generate artifacts: OpenAPI Documentation files are supposed to be coming from trusted sources. Trying to handle source files from untrusted sources and potentially causing HTML injection is out of the scope of this library.

Limitations

  • Partial support for Parameter properties: style, allow_reserved, explode are not handled.
  • Doesn't implement validation of values, currently it is only concerned in generating code from a higher level API (it might be extended in the future with classes for validation).
  • The features to generate artifacts from OpenAPI Documentation currently support only Version 3 of the specification.

Styles

StyleInt valueDescription
MKDOCS1Markdown for MkDocs and PyMdown extensions.
MARKDOWN2Basic Markdown.
HTML3Plain HTML (planned, not yet implemented).
PLANTUML_SCHEMAS100PlantUML schema for components schemas.
PLANTUML_API101PlantUML schema for API endpoints.

Supported sources for OpenAPI Documentation

SourceExample
YAML file./docs/swagger.yaml
JSON file./docs/swagger.json
URL returning YAML on HTTP GEThttps://example-domain.net/swagger/v1/swagger.yaml
URL returning JSON on HTTP GEThttps://example-domain.net/swagger/v1/swagger.json

Keywords

FAQs


Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc