친절한 API 사양서 만들기

동기 부여

REST API를 작성해도 어떤 명령으로 어떤 엔드포인트에
무엇이 있는지, 얼마나 많은 API가 있는지 모르기 때문에 알고 싶습니다.

API 설계 도구

다양한 도구가 나오는 것 같습니다.

API Blueprint

Swagger(OpenAPI)

apiary

2016년 1월에 Swagger는 OpenAPI가 된 경위가 있다고 합니다.
API 설계의 표준화를 목표로 하고 있는 것 같습니다.

Swagger (OpenAPI) 도입

아래와 같은 환경을 상정하고 있으므로, hapi용의 swagger 모듈이다
hapi-swagger 공식 사이트 (https://github.com/glennjones/hapi-swagger)
Quick Start를 바탕으로 설치해 봅니다.

환경
OS : macOS High Sierra
NodeJS : v9.5.0
hapi : v17.0.0

npm install hapi-swagger --save
npm install inert --save
npm install vision --save

샘플 코드 실행

Quick Start의 코드가 조금 잘못되어 있기 때문에
수정된 다음 코드 실행
Routes 부분은 적절하게 변경할 필요가 있다.

hoge.js

const Hapi = require('hapi');
const Inert = require('inert');
const Vision = require('vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');
const Joi = require('joi');


(async () => {
    const server = await new Hapi.Server({
        host: 'localhost',
        port: 3000,
    });

    const swaggerOptions = {
        info: {
                title: 'Test API Documentation',
                version: Pack.version,
            },
        };

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    try {
        await server.start();
        console.log('Server running at:', server.info.uri);
    } catch(err) {
        console.log(err);
    }

    server.route({
        method: 'GET',
        path: '/todo/{id}/',
        config: {
            handler: function(request, h){
                return "本来なら戻り値をかくよ"
            },
            description: 'Get todo',
            notes: 'Returns a todo item by the id passed in the path',
            tags: ['api'], // ADD THIS TAG
            validate: {
                params: {
                    id : Joi.number()
                            .required()
                            .description('the id for the todo item'),
                }
            }
        },
    });
})();

node hoge.js에서 실행해보기

아래와 같은 화면이 표시된다


value에 값을 넣고 Try it out 버튼을 누르면
API 실행시의 curl이나 리퀘스트, 리스폰스가 아래와 같이 표시된다.


javadoc에 코드 실행 기능이 붙은 것 같은 편리하고 좋은 감자!