스웨거(Swagger)의 기본구조 : Info 객체와 Base URL

 

스웨거의 기본구조 : Info 객체와 Base url

 

스웨거는 JSON 또는 YAML을 사용하여 만들어진다고 합니다.
아래의 예제는 YAML을 사용하지만 JSON으로도 똑같이 사용된다는 것을 생각해주세요.

 

 

swagger: "2.0" 
info: 
  title: Sample API 
  description: API description in Markdown. 
  version: 1.0.0 
host: api.example.com 
basePath: /v1 
schemes: 
  - https 
paths: 
  /users: 
    get: 
      summary: Returns a list of users. 
      description: Optional extended description in Markdown. 
      produces: 
        - application/json 
      responses: 
        200: 
          description: OK 

 

위와 같은 YAML 문법으로 정보를 표현한다.
그럼 위의 예제의 윗줄 부터 하나씩 무슨 것을 의미하는지 분석해보자.

 

 

 

---

메타데이터

스웨거 파일의 데이터에 대한 정보를 표기하는 방법이다.

 

swagger: "2.0"

스웨거 버전을 표기한다. 위의 예제는 스웨거 2.0을 사용한다는 뜻이다.

 

info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

이제는 좀 더 스웨거 파일에 대한 상세정보를 표기하는 방법이다.
Info 객체를 사용하여 만든다.

 

info-title : 스웨거 파일의 제목이다. API의 이름이라고 생각해도 될 것이다.
info-descripition : 추가설명을 표기할 수 가 있다.
info-version : 스웨거의 버전이 아닌, API의 버전을 명시한다.

 

 

 

 

 

 

---

베이스 URL

host: api.example.com
basePath: /v1
schemes:
  - https

 

모든 API 콜들의 베이스 url은 host basePath, schemes로 정리된다.
위의 예제를 api의 url로 변환하면 아래와 같다.
https://api.example.com/v1

 

모든 API경로들은 위와 같이 schemes와 host 그리고 basePath가 합쳐진 주소가 
기본 경로로 설정되어 있는 것으로 보면 된다.
이 스웨거 파일에서 /test 라고 되어있는 부분은
https://api.example.com/v1/test 라고 봐야한다.