swagger(open api) 시작

이 페이지 정보

Mac과 vscode에 swagger 개발 환경을 구축하고 api document를 만들 때까지가 썼습니다.

배경

api 사양서를 쓰는데 블루프린트를 사용하고 있습니다만, 다른 것도 시도하고 싶어졌기 때문입니다(내가 선정하고 있지 않기 때문에)

agreed 이라는 정의를 간단하게 걸리는 녀석을 사용해 보았습니다만
제약등의 기입을 할 수 없었기 때문에 채용을 보냈습니다(필수 제약 넣을 수 없는 괴로운)

목표

이런 문서를 만들 수 있습니다.

절차

vscode 설정

yaml extension 설치

구성 파일에 추가 설명

"yaml.schemas": {
    "https://raw.githubusercontent.com/kogosoftwarellc/open-api/master/packages/openapi-schema-validator/resources/openapi-3.0.json": ["*swagger.yaml", "*swagger.yml"],
},

swagger viewer 설치

Shift + Alt + P로 yaml에 설명 된 doc의 미리보기가 가능합니다.

쓰기

인증 주위

응답과 schema 정의 등

query parameter 등

yaml의 내용을 HTML로 만들고 싶습니다.

누군가에게 전달할 때 필요합니다.

$ docker run -i yousan/swagger-yaml-to-html < your-swagger.yml > ./build/index.html

swagger-codegen 설치

(클라이언트 등 필요하다면)

$ brew cask install adoptopenjdk8 && \
brew instal swagger-codegen

참고

VSCode에서 swagger 2.0의 yaml 문서를 편안하게 작성하고 싶습니다.

OpenAPI (Swagger) 초입문

Swagger의 Spec YAML 파일을 HTML로 변환