테스트 사례에서 API 문서를 생성하는 데 도움이 되는 도구를 만듭니다.

API 문서를 작성하는 것은 내가 싫어하는 일이고 처음부터 OpenAPI 문서를 작성하는 것은 악몽입니다.

일부 자동 API 생성 도구를 확인했는데 주석이나 데코레이터를 추가하여 코드를 수정해야 합니다. 코드를 가능한 한 깨끗하게 유지하고 싶기 때문에 개인적으로 좋아하지 않습니다.

그런 다음 일반적으로 단위 테스트는 API의 모든 사례를 다루기 때문에 단위 테스트를 기반으로 API 문서를 생성할 수 있는지 생각했습니다. 테스트 사례를 이해하고 API 문서를 생성하는 프로그램만 있으면 됩니다.

그래서 저는 Outdoc을 빌드하고 다음은 익스프레스 애플리케이션의 예입니다.

app.js

const express = require('express');
const app = express();

app.get('/projects', (req, res) => {
  res.json([{
    id: '1',
    name: 'project v1'
  }, {
    id: '2',
    name: 'project v2'
  }]);
});

app.test.js

const request = require('supertest');
const app = require('./app.js');

describe('api testing', () => {
  it('should able to find all', (done) => {
    request(app)
      .get('/projects')
      .set('x-api-key', 'outdoc-test')
      .expect(200)
      .end(function(err, res) {
        if (err) throw err;
        done();
      });
  });
});

Outdoc을 사용하려면 app.js에 몇 가지 코드를 추가하고 스크립트를 실행하기만 하면 됩니다.

app.js

const express = require('express');
const app = express();

// New added for using Outdoc
if (process.env.NODE_ENV === "test") {
  const { OutDoc } = require('outdoc');
  OutDoc.init();
}

패키지.json

{
  "scripts": {
    "test": "mocha *.test.js",
    "gen-doc": "outdoc npm test"
}

npm run gen-doc를 실행하면 다음과 같이 api.yaml을 얻습니다.

openapi: "3.0.1"
info:
  title: "API Document"
  version: "1.0.0"
paths:
  /projects:
    get:
      parameters:
        - in: "header"
          name: "x-api-key"
          example: "outdoc-test"
          schema:
            type: "string"
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "string"
                      example: "1"
                    name:
                      type: "string"
                      example: "project v1"

Outdoc은 여러 엔드포인트에 대한 태그를 자동으로 생성할 수도 있습니다.

Github에서 더 많은 옵션과 예를 확인하십시오https://github.com/dapi-labs/outdoc.