Express에서 즉석에서 문서 생성

17500 단어 expressnodewebdev
나는 얼마 전에 내가 구축하려고 했던 일부 HTTP API에 대한 문서를 생성하기로 결정했습니다. API는 내부적으로 사용되기 때문에 API Blueprint , Apiary 또는 Swagger 과 같은 온라인 솔루션에 커밋하고 싶지 않았습니다. 그리고 무언가를 처음부터 설정하는 것은... 조금 많았을 것입니다. 또한 문서를 작성하기 위해 모든 종류의 컨텍스트 전환을 피하면서 문서가 코드 내에 통합되기를 원했습니다.

나는 jsdoc 및 esdoc 에 대해 알고 있었는데 둘 다 주석에 문서를 작성할 수 있게 해줍니다. 그러나 그들의 임무는 HTTP API가 아닌 자바스크립트 코드를 문서화하는 것입니다. 그런 다음 주석에서 swagger/OpenAPI 사양을 생성하는 도구 swagger-jsdoc 를 찾았습니다. 이것은 내가 찾고 있던 것입니다.

이제 몇 가지 코드를 보자



동물을 나열하는 간단한 서버와 좋아하는 동물도 추가할 수 있습니다. 꽤 참신한 개념입니다.

const express = require('express');
const bodyparser = require('body-parser');

const app = express();
app.use(bodyparser.json({
  strict: false,
}));

const animals = [
  'panda', 'racoon', 'python',
];

app.get('/list', (req, res) => {
  return res.json(req.query.sort === 'yes' ? Array.from(animals).sort() : animals); // why is .sort inplace 😠
});

app.post('/add', (req, res) => {
  animals.push(...req.body.animals);
  return res.json({
    message: 'Added',
  });
});

app.listen(3000, () => {
  console.log('Server started at port 3000');
});

swagger-jsdoc에는 OpenAPI Specification을 따라야 하는 주석이 필요하며 이는 매우 직관적입니다.
/list 경로에 대한 설명서 주석을 추가합니다.

/**
 * @swagger
 * /list:
 *   get:
 *     summary: List all the animals
 *     description: Returns a list of all the animals, optionally sorted
 *     tags:
 *       - animals
 *     parameters:
 *       - in: query
 *         name: sort
 *         type: string
 *         required: false
 *         enum:
 *           - yes
 *           - no
 *     responses:
 *       200:
 *         description: List of animals
 *         schema:
 *           type: object
 *           properties:
 *             animals:
 *               type: array
 *               description: all the animals
 *               items:
 *                 type: string
 */

app.get('/list', (req, res) => {
  // ...
});


첫 번째 줄은 @swagger로 이 주석 블록을 swagger(OpenAPI) 사양으로 식별하는 데 도움이 됩니다swagger-jsdoc. 다음 몇 줄은 경로, 방법, 간략한 요약 및 설명을 정의합니다. tags는 API를 그룹화하는 데 사용됩니다.

다음은 query 및 path 예상 매개변수에 대해 설명합니다. Google/list API는 전송하기 전에 동물 목록을 정렬해야 하는지 여부를 결정하는 데 사용되는 선택적sort 쿼리 매개변수를 예상합니다.

그런 다음 응답을 정의합니다. 상태가 먼저 표시되고 약간의 설명이 표시된 다음 응답의 스키마가 표시됩니다. 여기서 JSON을 반환합니다. 그러나 다른 콘텐츠 유형도 쉽게 문서화할 수 있습니다.
/add 요청에 대해서도 동일하게 수행합니다.

/**
 * @swagger
 * /add:
 *   post:
 *     summary: Add more animal
 *     description: Add animals to the list
 *     tags:
 *       - animals
  *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               animals:
 *                 type: array
 *                 items:
 *                   type: string
 *     responses:
 *       200:
 *         description: Adds the animals in body
 *         schema:
 *           type: object
 *           properties:
 *             message:
 *               type: string
 *               default: 'Added'
 */
app.post('/add', (req, res) => {
  // ...
});


이제 주석이 준비되었으므로 swagger-jsdoc 모듈을 연결할 것입니다.

// ... other modules
const swaggerJSDoc = require('swagger-jsdoc');

const app = express();
app.use(bodyparser.json({
  strict: false,
}));

const animals = [
  'panda', 'racoon', 'python',
];

// -- setup up swagger-jsdoc --
const swaggerDefinition = {
  info: {
    title: 'Animals',
    version: '1.0.0',
    description: 'All things animlas',
  },
  host: 'localhost:3000',
  basePath: '/',
};
const options = {
  swaggerDefinition,
  apis: [path.resolve(__dirname, 'server.js')],
};
const swaggerSpec = swaggerJSDoc(options);

// -- routes for docs and generated swagger spec --

app.get('/swagger.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

// other routes


이것은 /swagger.json 에서 스웨거 사양을 제공합니다. 남은 일은 이 사양을 보다 인간 친화적인 방식으로 렌더링하는 것입니다. 나는 그것을 위해 ReDoc을 선택합니다. 간단한 설정이 있습니다.

HTML 파일 포함

<!DOCTYPE html>
<html>
  <head>
    <title>Quizizz Docs</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <link rel="shortcut icon" type="image/x-icon" href="https://quizizz.com/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!-- we provide is specification here -->
    <redoc spec-url='http://localhost:3000/swagger.json' expand-responses="all"></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>


우리는 이미 서버 JSON 사양에 대한 장소로 http://localhost:3000/docs/swagger.json를 설정했습니다. 이 HTML도 제공할 경로를 설정해 보겠습니다.

app.get('/docs', (req, res) => {
  res.sendFile(path.join(__dirname, 'redoc.html'));
});


결과,



There are more components to OpenAPI and swagger-jsdoc which make the process easier. You can write definitions for schemas/requests/responses that are used more than once and then use them in the docs. Check out Components Section | Swagger and Getting Started | Swagger JSDoc to define them in a JavaScripty way.

Code can be found here

트리와 accordion
어셈블리 상속 트리

좋은 웹페이지 즐겨찾기

개발자 우수 사이트 수집

개발자가 알아야 할 필수 사이트 100선 추천 우리는 당신을 위해 100개의 자주 사용하는 개발자 학습 사이트를 정리했습니다
best100-homepage