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
|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:
| 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 |
pip install open-api-schemas-to-markdown
The package provides a command line tool.
$ oa-to-md -h
usage: oa-to-md [-h] input_filepath output_filepath [locale]
positional arguments:
input_filepath The OpenAPI 3 YAML filepath
output_filepath The desired output filepath of the Markdown file
locale Locale to use when generating the Markdown file. Available:
en, fr
optional arguments:
-h, --help show this help message and exit
Example:
oa-to-md open_api.yml documentation.md
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 ».
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent