OpenAPI+ReDoc를 통한 자동 문서 Schema 정의

ReDoc에서 Schema 정의를 자동으로 문서화할 수 없습니다.

ReDoc Interactive Demo
OpenAPI의 API 규격서를 사용한 문서화 ReDoc는 매우 편리하지만 매우 큰 문제가 있다.Schema 정의는 자동으로 문서화할 수 없습니다.
자동화할 수는 없지만 문서화하는 방법이 있다.

Schema 정의의 문서화

tags:
  - name: pet_model
    x-displayName: The Pet Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Pet" />
  - name: store_model
    x-displayName: The Order Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Order" exampleRef="#/components/examples/Order" showReadOnly={true} showWriteOnly={true} />
x-tagGroups:
  - name: Models
    tags:
      - pet_model
      - store_model

tags의 항목description에 <SchemaDefinition schemaRef="" />을 추가하면 문서에서 내보냅니다.

    description: |
      ## Pet
      <SchemaDefinition schemaRef="#/components/schemas/Pet" />

이렇게 넣으면見出し2 왼쪽 창의 메뉴에 "Pet"을 표시할 수 있습니다.
추가<SchemaDefinition schemaRef="" /> 후 경과ReDoc의 이슈를 확인할 수 있다.토론을 봐도 자동화 목표가 없는 것 같다.
필요한 모형을 손으로 쓸 때마다 힘들기 때문에 자동으로 정리하는 CLI 도구를 만들었다.

Schema 정의 자동 요약

OpenAPI Redoc Schema Definition - dforest/openapi-redoc-schema-def
이렇게 하면 지정된 레이블이 있는 Schema 정의가 tags의 description에 요약됩니다.

tags:
  - name: model
    ## Hoge
    <SchemaDefinition schemaRef="#/components/schemas/Hoge" />

설치하다.

Python 3이 필요한 실행 환경을 실행합니다.아직 포장되지 않았으므로 GiitHub에서 소스 파일을 가져와 설치하십시오.

pip install git+https://github.com/dforest/openapi-redoc-schema-def

사용법

OpenAPI의 YAML을

openapi-redoc-schema-def --path [Path to yaml] --tags [Tags for schema component(s)]

--path [Path to yaml]에 지정합니다.--tags [Tags for schema component(s)]에 요약할 태그를 지정합니다.공백 구분자를 사용하여 여러 태그를 지정할 수 있습니다.
단지 자신을 위해 간단하게 한 것일 뿐, 부족한 기능과 오류가 있을 수 있다.나는 홍보를 기다리고 있다.

YAML이 여러 개 있을 때.

ReDoc는 원래 여러 개의 YAML을 지원하지 않기 때문에 이것openapi-redoc-schema-def도 여러 개의 YAML을 지원하지 않는다.이 경우 분산된 YAML을 하나의 YAML에 모아 재활용해야 한다openapi-redoc-schema-def.
나는 t2y/openapi-ext-tools: extended tools for openapi spec를 사용하여 그것을 하나의 YAML로 정리한 다음에 그것을 진행한다openapi-redoc-schema-def.