정적 문서 내보내기

swagger 를 작성하는 프로젝트의 경우 보통 url 전달로 API 명세를 소통합니다. 하지만 망 분리 등의 이슈로 직접 접근이 불가능한 경우 부득이하게 문서를 전달해야 되는 경우가 있습니다. 이 때 만약 명세를 위한 문서를 별도로 작성한다면 문서와 실제 API 의 간극이 발생합니다. 다행히 swagger 는 이를 보완하기 위한 기능을 제공하고 있습니다.

1. boot sample project with swagger

• 3개의 sample API 구현

• sample respone spec 확인 가능

2. export schema (json)

• url 가져오기

  • /v3/api-docs 링크를 누르거나

  • console 에서 명령어를 통해 url 을 가져옵니다.

// 3.x
> ui.getConfigs().url

// 2.x
> swaggerUi.api.url

3. check schema

4. convert to document

• https://editor.swagger.io/

• json 을 붙여넣기만 하면 완성!

• 필요시 yml 전환 가능

Reference

How to export swagger.json (or yaml)Stack Overflow

Documenting a Spring REST API Using OpenAPI 3.0 | BaeldungBaeldung on Kotlin