Skip to main content

Generate Markdown documentation from OpenAPI 3 Components Schemas

Project description

Software License CircleCI PyPI

OpenAPI Components Schemas to Markdown

The goal of this package is to generate Github Flavored Markdown documentation of Components Schemas from the OpenAPI 3 specification.

Say you've got a YAML file:

openapi: "3.0.0"
info:
  version: "0"
  title: Demo
paths:
  /demo:
    get:
      summary: Demo
      responses:
        '200':
          description: OK
components:
  schemas:
    ResultatHumain:
      properties:
        operation_id:
          type: integer
          format: int64
          description: Le numéro unique de l'opération
          example: 1119920371
        categorie_personne:
          type: string
          description: Indique la catégorie de personne impliquée dans le bilan humain
          example: Pêcheur français
        resultat_humain:
          type: string
          description: Description du bilan humain
          example: Personne secourue
        nombre:
          type: number
          format: int32
          minimum: 0
          description: Nombre de personnes impliquées dans ce bilan
          example: 3
        dont_nombre_blesse:
          type: number
          format: int32
          minimum: 0
          description: Indique le nombre de personnes blessées dans le bilan
          example: 1

The package will produce a Markdown file from the YAML specification file with the following content:

## ResultatHumain Model
|Field|Type|Description|Example|Properties|
|---|---|---|---|---|
|operation_id|integer($int64)|Le numéro unique de l'opération|1119920371||
|categorie_personne|string|Indique la catégorie de personne impliquée dans le bilan humain|Pêcheur français||
|resultat_humain|string|Description du bilan humain|Personne secourue||
|nombre|number($int32)|Nombre de personnes impliquées dans ce bilan|3|minimum: 0|
|dont_nombre_blesse|number($int32)|Indique le nombre de personnes blessées dans le bilan|1|minimum: 0|

And if you render it:

ResultatHumain Model

Field Type Description Example Properties
operation_id integer($int64) Le numéro unique de l'opération 1119920371
categorie_personne string Indique la catégorie de personne impliquée dans le bilan humain Pêcheur français
resultat_humain string Description du bilan humain Personne secourue
nombre number($int32) Nombre de personnes impliquées dans ce bilan 3 minimum: 0
dont_nombre_blesse number($int32) Indique le nombre de personnes blessées dans le bilan 1 minimum: 0

Installation

pip install open-api-schemas-to-markdown

Usage

The package provides a command line tool.

$ oa-to-md -h
usage: oa-to-md [-h] input_filepath output_filepath

positional arguments:
  input_filepath   The OpenAPI 3 YAML filepath
  output_filepath  The desired output filepath of the Markdown file

optional arguments:
  -h, --help       show this help message and exit

Example:

oa-to-md open_api.yml documentation.md

Notice

This software is available under the MIT license and was developed as part of the Entrepreneur d'Intérêt Général program by the French government.

Projet développé dans le cadre du programme « Entrepreneur d’intérêt général ».

Project details


Release history Release notifications

This version
History Node

0.1.3

History Node

0.1.2

History Node

0.1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
open_api_schemas_to_markdown-0.1.3-py2-none-any.whl (4.6 kB) Copy SHA256 hash SHA256 Wheel py2 Apr 20, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page