Swagger

참조:동빈나님의 유튜브

1. API 명세

• api 명세는 긴 프로젝트의 다양한 포지션의 개발자가 존재할 때 많은 도움이 된다.
• 짧은 프로젝트, 경력이 짧은 개발자들간의 프로젝트에서는 오히려 발목을 잡을 위험이 있음

2. Open-API

• Rest API를 작성하도록 도와준다
• JSON, YAML 형식

3. Swagger

• 특정한 프로그램의 존재하는 API 기능 명세 및 테스트 가능
• 스웨거 허브에서 제공
  • 그나마 api 명세를 덜 번거롭게 할 수 있다.
  • 기본적으로 Rest API 제공

3-1. 2가지 방식

1. 특정한 서버 프로그래밍 언어를 이용하여 swqgger API를 종속적인 형태로 이용하는 방식(스프링: 어노테이션)
2. 어떤 프로그래밍 언어를 거치지 않고 swagger API를 별도의 웹문서로 빼내서 독립적으로 이용하는 방식(yaml 파일) - petstore template

-> 이번 설명은 모든 프로그래밍 언어에서 독립적인 yaml 방식에 대해 다루겠다.

3-2. 같이 사용하기 좋은 사이트

JSONPlaceholder

• 가상의 API를 받아 데이터를 보내주는 사이트

3-3. swagger 사용법

• 각 용어 설명

  - description : 설명
  - url : 받을 url
  - paths : api 
    - get: get 방식
      - summary : 설명
      - parameters: 파라미터가 어떠한 형태로 가는지
        - name: 파라미터 이름
        - in : path - 실제 url에 어떤 변수가 들어간다고 가정하는 것
        - required: 반드시 name이 들어가야 한다는 것을 의미
        - descritption : 설명
        - shema :
        	- type: 파라미터의 타입(integer)
        - responses : 응답에 대한 내용
        	'200':
            - description : 설명
            - content:
            	application/json: json 형태를 의미
                	- schema:
                    - type: 반환 타입
                    - properties: 객체안의 타입

• 사용법

   /api/example:
    get:
      summary: 요청 목록 가져오기
      parameters: 		// 요청
      - name: ChatRoomID 	// 변수 이름
        in: query 		// 어떻게 보낼지
        description: 설명	// 설명
        required: true 		// 필수인지
        schema:
          type: number
        example:
          1
      - name: index
        in: query
        description: 설명
        required: true
        schema:
          type: number
        example:
          2
      responses: // 응답
        '200':
          description: 요청 목록
          content:
            application/json:
              schema:
                type: object
                properties: // 타입이 객체일 때 그 안의 내용을 의미한다.
                  data:
                    type: array 
                    items: // 타입이 배열일 때 그 안의 어떤 값이 들어오는지를 의미한다.
                      type: object
                      properties:
                        from:
                          type: string
                        to:
                          type: string
                        info: 
                          type: object
                          properties:
                            id:
                              type: string
                            image:
                              type: string
                            location:
                              type: string
                            age:
                              type: number
                            info:
                              type: string
                        state:
                          type: string  
              example:
                {
                  data: [
                    {
                      from: "철수",
                      to: "영희",
                      info: {
                        id: "happy",
                        image: "Isfg",
                        location: "강서",
                        age: 25,
                        info: "안녕하세요",
                      },
                      state: "대기중",
                    },
                    {
                      from: "영희",
                      to: "철수",
                      info: {
                        id: "surpriese",
                        image: "Imazgfge",
                        location: "강남",
                        age: 26,
                        info: "안녕하세요",
                        member: [],
                      },
                      state: "대기중",
                    },
                  ],
                }

3-4. 웹 문서용 swagger UI

• swagger hub는 직접 위의 것을 다 적어야 하는 것도 괜찮지만 별도의 url에 웹 문서를 띄어서 독립적인 swagger url을 사용 가능