OpenAPI组件模式到Markdown

此包的目标是从OpenAPI 3规范生成组件模式的Github Flavored Markdown文档。

假设你有一个YAML文件

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

该包将从YAML规范文件生成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|

如果你将其渲染

ResultatHumain

安装

pip install open-api-schemas-to-markdown

用法

该包提供了一个命令行工具。

$ 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

示例

oa-to-md open_api.yml documentation.md

注意

此软件可在MIT许可下使用，并由法国政府作为Entrepreneur d'Intérêt Général计划的一部分开发。

在“Entrepreneur d'intérêt général”计划下开发的项目。