express에서 swagger 사용

참고

htps : // 기주 b. 이 m/스 r네 t/스윕게 rjs도 c/bぉb/어쨌든 r/도 cs/게짱 G-S R데. md

전제 지식

하향식 또는 상향식

swagger의 경우,

Swagger Spec을 기술하고 그것에 기초한 API (모의)를 생성하는 방법 (하향식)

기존 API에 주석을 작성하고 Swagger Spec을 생성하는 방법 (상향식)

의 2개의 형식의 이용 방법이 있다. 물론 조합도 있다고는 생각합니다.
제 경우에는 후자의 상향식을 사용하는 경우가 많기 때문에 그 방법을 아래에 설명합니다.

그렇다고는 해도, 결국 어노테이션 자체를 자동 생성해 주는 것이 아니기 때문에 하향식으로 써도 괜찮은 것은? 라고 생각합니다.

swagger-ui

하향식이든 상향식이든 사양을 문서화하기 위해 작성한 (또는 생성 된) Swagger Spec을 swagger-ui에서 볼 수 있습니다.

swagger-ui는 여기에서 다운로드하거나 clone하여 그대로 dist/index.html을 열면 움직입니다.

http를 경유하지 않을 것 같습니다.

필요한 것 준비

설치

npm install express
npm install swagger-jsdoc

swagger-ui는 이미 위에서 다운로드했다고 가정합니다.

구현

통상은 여러가지 파일을 나누는 것입니다만, 여기에서는 일단 1개의 파일에 기술해 보았습니다.

app.get('/api-docs.json', function(req, res){});

를 정의하기 전까지는 swagger를 이용하기 위한 설명으로, api-docs.json을 반환하기 위한 설명입니다.
그 외는 app.post('/login', function(req, res){}); 와 그 사양을 기술하고 있습니다 (긴・・・).

index.js

var express = require('express');
var app = express();
var swaggerJSDoc = require('swagger-jsdoc');

//クロスサイト対応。swagger-uiから見た際、クロスサイトのエラーがでることへの対応。
app.use(function(req, res, next) {
    res.header("Access-Control-Allow-Origin", "*");
    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
    next();
});

//swaggerの基本定義
var options = {
    swaggerDefinition: {
        info: {
            title: 'Hello World',
            version: '1.0.0.'
        },
    },
    apis: ['./index.js'], //自分自身を指定。外部化した場合は、そのファイルを指定。配列で複数指定も可能。
};

var swaggerSpec = swaggerJSDoc(options);

//swagger-ui向けにjsonを返すAPI
app.get('/api-docs.json', function(req, res){
    res.setHeader('Content-Type','application/json');
    res.send(swaggerSpec);
});

// 以下、使用を定義するAPI

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
    res.json(req.body);
});

//listen
app.listen(3000, function(){
    console.log("Listen on port 3000.");
});

알면 쉽지만 알기까지 힘들었습니다.

사용

시작

node index.js

api-docs.json 얻기

에 액세스.

{"info":{"title":"Hello World","version":"1.0.0."},"swagger":"2.0","paths":{"/login":{"post":{"description":"Login to the application","produces":["application/json"],"parameters":[{"name":"username","description":"Username to use for login.","in":"formData","required":true,"type":"string"},{"name":"password","description":"User's password.","in":"formData","required":true,"type":"string"}],"responses":{"200":{"description":"login"}}}}},"definitions":{},"responses":{},"parameters":{},"securityDefinitions":{},"tags":[]}

swagger-ui에서 탐색

swagger-ui/dist/index.html을 엽니다.

http://localhost:3000/api-docs.json 을 상단의 탐색 왼쪽 텍스트 상자에 넣고 탐색 버튼을 누릅니다.

HelloWorld 페이지가 표시되면 OK.

기타

swagger-editor

swagger-editer 자체는 온라인 버전 을 사용하거나 로컬 낙하로 사용할 수 있습니다. 시도하는 것만으로는 대단히 온라인 버전으로 좋을까.