Swagger를 사용하여 모의 서버를 설정하기 전의 단계

이 기사에서는 다음 내용을 설명합니다.

Swagger의 기초 개념

Swagger Editor를 사용하여 API 문서 만들기

Swagger에서 만든 API 문서를 기반으로 모의 서버를 설정합니다.

Swagger란?

공식

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Swagger는 OpenAPI(OAS)를 위한 세계 최대의 API 개발 프레임워크로, API 수명 주기 전반에 걸쳐 설계부터 문서화, 테스트 및 배포까지 가능합니다.

그렇기 때문에 API의 사양 설계뿐만 아니라 테스트와 배포까지 해주는 편리한 도구입니다.

기본 용어

Swagger 를 배우면 여러가지 용어가 여기저기 날아오므로, 먼저 여기에서 이야기를 정리해 둡니다.
이번에는 필요한 최소한의 용어와 사용하는 녀석의 이름만 픽업했습니다.

Swagger Specification

Swagger를 다루는데 중심이 되는 개념으로, Swagger의 스펙에 준한, RESTful API 인터페이스를 기술하기 위한 포맷( YAML/JSON ).

Swagger Editor

Swagger Specification 편집기. 익숙해질 때까지 시간이 걸린다.

Swagger UI

Swagger Specification 에서 동적으로 문서를 생성하는 도구. 매우 보기 쉽다.

Swagger Codegen

Swagger Editor로 작성한 내용을 그대로 코드에 써낸다. 다양한 언어에 대응하고 있어 언어뿐만 아니라 FW에도 대응하고 있다.

Swagger Editor를 사용하여 Swagger Specification을 만들고 API 사양을 만듭니다.

자세한 문법은 여기를 참조하십시오.

PENAPI SPECIFICATION

여기에서는 @Fendo181 가 작성한 lumen 의 간단한 API 를 예로 작성해 갑니다.

htps : // 기주 b. 코 m / 후엔도 181 / 페멘

# Get all authors 
GET /api/authors

# Get one author
GET /api/authors/23

#Create an author
POST /api/authors

#Edit an author
PUT /api/authors/23

# Delete an author
DELETE /api/authors/23

세부 정보 : htps : // 기주 b. 코 m/후엔도 181/페멘_아테오 rs_아피/이스에 s/2

예를 들어 Swagger Editor 에서 문서를 작성해 보겠습니다.

swagger: '2.0'
info:
  description: |
    サンプルです. 

    You can findout more about Swagger at 
    [http://swagger.io](http://swagger.io) or on 
    [irc.freenode.net, #swagger](http://swagger.io/irc/).
  version: "1.0.0"
  title: Lumen Authors API 
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
# host: petstore.swagger.io
# basePath: /v2

tags:
- name: authors
  description: Authors Info
  externalDocs:
    description: Find out more
    url: http://swagger.io
# schemes:
# - http
paths:
  /authors:
    get:
      tags:
      - authors
      summary: Get all author by id
      consumes:
      - application/json
      - application/xml
      produces:
      - application/json
      - application/xml
      responses:
        200:
          description: Successful
          schema:
           $ref: '#/definitions/Author'
    post:
      tags:
      - authors
      summary: Create an new author
      produces:
      - application/json
      - application/xml
      parameters:
      - in: body
        name: body
        description: Add New Author 
        required: true
        schema:
          $ref: '#/definitions/Author'
      responses:
        200:
          description: Success
  /authors/{id}:
    get:
      tags:
      - authors
      summary: Get an author by id
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: The id that needs to be fetched.  
        required: true
        type: string
      responses:
        200:
          description: successful 
          schema:
           $ref: '#/definitions/Author'
        400:
          description: Invalid id supplied
        404:
          description: User not found
    put:
      tags:
      - authors
      summary: Updated author by id
      description: Update Author info
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: name that need to be updated
        required: true
        type: string
      - in: body
        name: body
        description: Updated user object
        required: true
        schema:
          $ref: '#/definitions/Author'
      responses:
        200:
          description: author info
    delete:
      tags:
      - authors
      summary: Delete author by id
      description: This can only be done by the logged in user.
      produces:
      - application/json
      - application/xml
      parameters:
      - name: id
        in: path
        description: The name that needs to be deleted
        required: true
        type: string
      responses:
        200:
          description: Deleted Successfully
definitions:
  Author:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string
      github:
        type: string
      twitter:
        type: string
      location:
        type: string
      latest_article_published:
        type: string
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
# Added by API Auto Mocking Plugin
host: virtserver.swaggerhub.com
basePath: /Fendo181/APP/1.0.0
schemes:
 - https
 - http

이 ymal 로 쓰여진 Swagger Specification (왼쪽)을 바탕으로 Swagger UI (오른쪽)에서 쉽게 API 문서를 생성하는 것이 가능합니다.

이와 같이 순서로서는 Swagger Editer 로 Swagger Specification 를 기술해, SwaggerUI 를 보면서, API 의 사양을 설계해 나갈 방침이 된다고 생각합니다. 또한 작성한 API는 SwaggerHub에서 공개할 수 있습니다. 모의 서버를 세운다. SwaggerHub 에서 서버 파일을 출력하여 모의 서버를 구성해 봅시다. SwaggerHub 의 server 에서 지정된 환경을 선택하여 파일을 출력합니다.

이번은 nodejs-server 로 생각합니다.

내용의 구성은 다음과 같다. # tree nodejs-server-server-generated -L 1 [~/src/fendo181/lumen_authors_api][add-swagger-spec] nodejs-server-server-generated ├── README.md ├── api │ └── swagger.yaml #swagger 파일 ├── controllers │ └── Authors.js ├── index.js ├── node_modules ├── package-lock.json ├── package.json ├── service │ └── AuthorsService.js └── utils └── writer.js swagger.yaml에는 SwaggerHub로 작성된 Swagger Spec 파일이 그대로 기록됩니다. 이 swagger.yaml 을 바탕으로 서버의 처리가 기술되고 있는 것이, Authors.js 입니다. 여기의 Authors 는 임의의 이름이 됩니다. 브라우저에서 Swagger UI를 확인합니다. npm install을 실행합니다. $npm start > [email protected] prestart /Users/futoshi.endo/src/fendo181/lumen_authors_api/nodejs-server-server-generated > npm install up to date in 0.797s > [email protected] start /Users/futoshi.endo/src/fendo181/lumen_authors_api/nodejs-server-server-generated > node index.js Your server is listening on port 8080 (http://localhost:8080) Swagger-ui is available on http://localhost:8080/docs http://localhost:8080/docs로 이동하여 Swagger UI를 확인합니다. 여기서 각 엔드포인트별 처리를 확인할 수도 있습니다. Try It Out에서 브라우저에서 Response를 확인할 수 있습니다. 시험에 GET 처리를 확인해 봅시다. curl로 확인 GET $ curl -X GET --header 'Accept: application/json' 'https://virtserver.swaggerhub.com/Fendo181/APP/1.0.0/authors' { "id" : 0, "name" : "string", "email" : "string", "github" : "string", "twitter" : "string", "location" : "string", "latest_article_published" : "string" } 참고문헌