Swagger를 활용한 api documents 만들기 - 1탄 (Swagger Editor)

Swagger를 활용한 api documents 만들기 - 1탄 (Swagger Editor)

우리는 사용자들이 필요한 Application Program을 만들었을 것이며 거기에 필요한 Web과 Service들을 만들었을 것이다. 이것들을 자유롭게 언제든지 사용할 수 있게 Web Api를 만들텐데 만들고 사용할줄 알아야하는데 알려주지 않으면 사용하기 힘들고 파악하는데 시간이 많이 걸릴 것이다.

그래서 필요한게 Api Documents다.

Api를 만들기 위해 개고생한 우리들을 위해 다른사람들이 사용할 수 있게 Swagger를 활용한 Api Documents를 만들어 보자.

 

Swagger Editor 개요

• Swagger Editor의 문서 작성은 yaml 혹은 json 으로 작성 가능하며 실시간으로 확인할 수 있고 Swagger UI로 최종 버전을 확인할 수 있음.
  • Swagger 공식 주소 : https://swagger.io/ 
  • 참고 : https://editor.swagger.io/ (Edit → openapi로 변경 가능)
    • 아래왼쪽과 같은 형식의 코드로 작성되면 UI는 아래오른쪽과 같은 형태로 나타난다.

 

Swagger Editor 사용법

https://github.com/swagger-api/swagger-editor 에서 Clone 혹은 Download ZIP을 통해 프로젝트를 받는다.

 

  터미널(ctrl+`)에서 명령어 'npm start' 실행한다. (README.md 참고) (나는 vsc코드에서 사용중이다.)

아래와 같은 출력 내용으로 npm이 install되고 서버를 열게 될 것이다.

 

 

  http://localhost:3001로 접속하게 되면 https://swagger.io/ 와 같은 동일한 내용이 나타난다.

 

 

탭을 보면 작성되어있는 코드를 YAML로 저장할 수 있고 변환하여 JSON으로도 저장할 수 있는 기능을 갖추고 있다.

원하는 형태로 저장하여 사용할 수 있다.

 

 

Generate Server로는 작성되어 있는 코드를 Swagger UI 프로젝트로 변환시켜줄 수 있는데 원하는 언어의 프로젝트로 선택하면 압축파일이 만들어 진다.

 

나는 그 중에 nodejs-server를 선택했다.

 

 

'npm start' 명령어를 입력해주면 관련 라이브러리들이 설치되고 실행할 수 있는 주소가 나타나게 된다.

 

 

http://localhost:8080/docs 접속하면 swagger ui가 나타난다.

 

 

하지만 우리가 보기엔 이러한 UI는 웬 구닥다리 UI가 나온거지? 라는 의문이 들 것이다.

줘도 안쓸것 같은 느낌적인 느낌이랄까?

 

그래서 우리가 사용할 api는 openapi이다.

Swagger Editor로 YAML, JSON파일을 작성할 때 최상단에 있는 내용을 보면 swagger: "2.0" 라고 되어있다.

이 버전을 openapi버전으로 변경해 줘야 하는 것이다.

코드의 구조는 동일하나 형식이 다르다.

 

작성방법은 아래의 예시를 통해 확인할 수 있다.

Swagger Editor 프로젝트 안에 test/e2e/fixtures/petstore.openapi.yaml 파일이 존재하는것을 확인할 수 있을 것이다.

(자세한건 README.md에 openapi로 검색해보자.)

 

petstore.openapi.yaml에 있는 내용으로 Swagger Editor를 openapi버전으로 변경하고

nodejs-server 프로젝트를 받아 실행하면

 

 

 

깔끔하게 바뀐 Swagger UI가 나온다.

작성하는 방법은 공식 홈페이지를 참고하면 된다.

 

 

프로젝트 실행 및 관련 내용이 궁금하다면 프로젝트 내 포함되어 있는 파일인 README.md에 친절하게 나와있다.

 

 

 

Swagger UI 관련 내용은

Swagger를 활용한 api documents 만들기 - 2탄 (Swagger UI)에서 다루도록 하겠다.