Node.js + Swagger

필요 패키지

 - Swagger 형식에는 Yaml과 Json으로 설정하는 방식이 존재하는 데 Swagger 에서는 Yaml 방식을 정석으로 채택합니다.

---

YAML 방식

YAML 방식 필요 패키지

npm install swagger-cli swagger-ui-express yamljs
npm install -D @types/swagger-ui-express @types/yamljs

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "store"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"
  externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
schemes:
- "https"
- "http"
paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        "405":
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
출처: https://chamch-dev.tistory.com/19 [개발참치의 개발이야기:티스토리]

Swagger 적용


// 공통 사항
import swaggerUi from 'swagger-ui-express'

// yaml을 연동하기 위함
import YAML from 'yamljs'

...
// yaml 파일 연동
const swaggerYaml = YAML.load(path.join(__dirname, '../build/swagger.yaml'))

...
// yaml로 된 swagger 연동
app.use('/api-yaml', swaggerUi.serve, swaggerUi.setup(swaggerYaml))
출처: https://chamch-dev.tistory.com/19 [개발참치의 개발이야기:티스토리]

---

JSON 방식

JSON 방식 필요 패키지

npm install swagger-cli swagger-ui-express
npm install -D @types/swagger-ui-express

{
  "swagger": "2.0",
  "info": {
    "description": "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters.",
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "petstore.swagger.io",
  "basePath": "/v2",
  "tags": [
    {
      "name": "pet",
      "description": "Everything about your Pets",
      "externalDocs": {
        "description": "Find out more",
        "url": "http://swagger.io"
      }
    },
    {
      "name": "store",
      "description": "Access to Petstore orders"
    },
    {
      "name": "user",
      "description": "Operations about user",
      "externalDocs": {
        "description": "Find out more about our store",
        "url": "http://swagger.io"
      }
    }
  ],
  "schemes": [
    "https",
    "http"
  ],
  "paths": {
    "/pet": {
      "post": {
        "tags": [
          "pet"
        ],
        "summary": "Add a new pet to the store",
        "description": "",
        "operationId": "addPet",
        "consumes": [
          "application/json",
          "application/xml"
        ],
        "produces": [
          "application/xml",
          "application/json"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "Pet object that needs to be added to the store",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Pet"
            }
          }
        ],
        "responses": {
          "405": {
            "description": "Invalid input"
          }
        },
        "security": [
          {
            "petstore_auth": [
              "write:pets",
              "read:pets"
            ]
          }
        ]
      },
     }
    }
   }
  }
 }
출처: https://chamch-dev.tistory.com/19 [개발참치의 개발이야기:티스토리]

Swagger 적용

// 공통 사항
import swaggerUi from 'swagger-ui-express'

// json 파일을 바로 불러오기
import swaggerJson from './swaggerJson'


...

// json으로 된 swagger 연동
app.use('/api-json', swaggerUi.serve, swaggerUi.setup(swaggerJson))
출처: https://chamch-dev.tistory.com/19 [개발참치의 개발이야기:티스토리]

---

 

Node.js (typescript) - Swagger UI 연동

 

Swagger Editor