open API 명세서를 반환하는 API 작성

1) info : api에 대한 메타데이터, 이 정보는 문서 생성에 사용되며 클라이언트가 사용할 수 있다. 제목/버전 필수

2) server : api를 호스팅 하는 서버 목록이 선택적으로 포함된다. 호스팅 된 api 문서가 대화형인 경우 swagger ui에서 이를 사용해 api를 직접 호출하고 응답을 표시할 수 있다.  기본은 호스트된 문서 서버의 루트(/)를 가리킨다.

- 호스트 : 네트워크에 연결되어 있는 컴퓨터들, ip주소를 가지고 있고 양방향 통신이 가능한 컴퓨터

- swagger : Open Api Specifiaction (OAS)를 위한 프레임워크, OAS는 Restful 웹서비스를 약속된 규칙에 따라 API 스펙을 json과 yaml 형식으로 표현한다. 이를 통해 직접 소스코드를 보거나 추가 문서 필요 없이 서비스를 이해할 수 있다.

3) components : components 섹션에서 requestbodies(요청 페이로드) 및 response를 정의할 수 있다. 일반적인 요청 본문과 응답이 있을 때 유용

- paths : 엔드포인트 정의

- parameters : 필드 앞에 - 하이픈이 있는데 배열 요소로 선언하는데 사용된다. parameters 필드는 여러 매개변수를 포함할 수 있으며 실제로는 경로 및 쿼리 매개변수의 조합이므로 배열로 선언된다. 매개변수 필드에는 api 쿼리, 경로, 헤더 및 쿠키 매개변수가 포함된다.

- response : response는 응답 타입을 정의한다. 기본 필드로 HTTP 상태 코드가 포함되어 있다. HTTP 상태 코드가 될 수 있는 응답이 하나 이상 있어야 한다.

- requestbody : 요청 페이로드 객체를 정의하는데 사용한다. content는 response 객체에 대해 정의된 방식과 유사한 방식으로 정의. response로 components  섹션 아래에 재사용 가능한 requestbody를 만들고 $ref를 사용하여 직접 사용할 수 있다.

 

 

 

 

 

---

(참고)

https://velog.io/@springer/API-%EB%AA%85%EC%84%B8%EC%99%80-%EA%B5%AC%ED%98%84

https://gksdudrb922.tistory.com/218

https://velog.io/@jwpark06/Swagger-API-%EB%AA%85%EC%84%B8-%EB%A7%8C%EB%93%9C%EB%8A%94-%EB%B2%95-feat.-yaml-%ED%8C%8C%EC%9D%BC

https://ksyy.tistory.com/247