Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/entrepreneur-interet-general/open_api_schemas_to_markdown
Generate Markdown documentation from OpenAPI 3 Components Schemas
https://github.com/entrepreneur-interet-general/open_api_schemas_to_markdown
eig-2018 entrepreneur-interet-general github-flavored-markdown markdown openapi-documentation openapi3 predisauvetage
Last synced: 5 days ago
JSON representation
Generate Markdown documentation from OpenAPI 3 Components Schemas
- Host: GitHub
- URL: https://github.com/entrepreneur-interet-general/open_api_schemas_to_markdown
- Owner: entrepreneur-interet-general
- License: mit
- Created: 2018-04-19T09:07:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2018-10-03T11:27:39.000Z (about 6 years ago)
- Last Synced: 2024-10-21T15:39:43.437Z (26 days ago)
- Topics: eig-2018, entrepreneur-interet-general, github-flavored-markdown, markdown, openapi-documentation, openapi3, predisauvetage
- Language: Python
- Homepage: https://pypi.org/project/open-api-schemas-to-markdown/
- Size: 32.2 KB
- Stars: 11
- Watchers: 14
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/entrepreneur-interet-general/open_api_schemas_to_markdown/blob/master/LICENSE.md)
# OpenAPI Components Schemas to Markdown
The goal of this package is to generate [Github Flavored Markdown](https://github.github.com/gfm/) documentation of Components Schemas from the [OpenAPI 3 specification](https://github.com/OAI/OpenAPI-Specification).
Say you've got a YAML file:
```yml
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:
```markdown
## 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:
## 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|
## 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 [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
```
## 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](https://entrepreneur-interet-general.etalab.gouv.fr) by the French government.
Projet développé dans le cadre du programme « [Entrepreneur d’intérêt général](https://entrepreneur-interet-general.etalab.gouv.fr) ».