JSDoc은 앱 소스 코드의 주석에서 문서를 생성하는 데 널리 사용되는 도구입니다.
이것은 두 가지 목적을 제공합니다.
첫째, 문서는 소스 코드를 보는 모든 사람이 직접 사용할 수 있습니다.
둘째, 주석은 나중에 완전한 참조 문서 세트로 컴파일 할 수 있습니다.
Swagger는 이 문서를 표시하기 위한 도구 인 Swagger UI를 제공합니다.
Swagger UI는 OpenAPI 사양 정의에서 웹 페이지를 만듭니다. 이 튜토리얼에서 볼 수 있듯이 이러한 정의는 JSDoc 주석에서 직접 YAML로 작성할 수 있습니다.
이 자습서에서는 Express API에 대한 Swagger UI 설명서 웹 페이지를 설정합니다. 그런 다음 API의 소스 코드에 JSDoc 주석을 작성하여 OpenAPI 정의를 생성 할 수 있습니다. 마지막으로 Express API에 추가 된 사용자 지정 / docs 엔드 포인트에서 제공되는 OpenAPI 사양을 따르는 설명서가 있습니다.
전제 조건
이 자습서를 완료하려면 다음이 필요합니다.
샘플 Express API를 설치하고 실행하려면 먼저 저장소를 복제합니다 (test-api를 선택한 디렉토리 이름으로 바꿉니다).
git clone https://github.com/kabartolo/jsonplaceholder-express-api test-api다음으로 다음 명령을 실행하여 Express 서버를 시작합니다 (test-api를 방금 만든 디렉토리의 이름으로 바꿉니다).
cd test-api
npm install
npm run startAPI를 보려면 localhost:3000으로 이동하십시오. /users 및 /users/1에 대한 링크가 표시되어야 합니다.
JSONPlaceholder에서 사용자 데이터를 보려면 이들 중 하나로 이동하십시오.
이 튜토리얼에서 추가 된 코드는 저장소의 문서 브랜치에서 찾을 수 있습니다.
Terminology
OpenAPI는 사양의 이름이고 Swagger는 이 사양을 구현하는 도구 집합입니다. Swagger와 OpenAPI의 차이점은 무엇입니까?를 참조하십시오.
이 가이드에서는 OpenAPI에서 정의한 다음 API 관련 용어 및 정의를 사용합니다.
https://api.example.com/v1/users?role=admin&status=active
\________________________/\____/ \______________________/
server URL endpoint query parameters
pathlocalhost:3000 or example.com/api
API에서 데이터를 검색하는 데 사용되는 전체 URL은 기본 URL (localhost : 3000 / users)에 엔드 포인트를 추가하여 구성됩니다.
https://dev.to/kabartolo/how-to-document-an-express-api-with-swagger-ui-and-jsdoc-50do
1 단계 : 애플리케이션 설정
1.1 : swagger-jsdoc 및 swagger-ui-express 설치
JSDoc 주석에서 Swagger UI 페이지를 만들려면 문서를 Swagger UI로 전달하는 방법이 필요합니다.
swagger-jsdoc 및 swagger-ui-express를 Express API에 설치하려면 다음을 실행하십시오.
npm install swagger-jsdoc@5.0.1 --save-exact
npm install swagger-ui-express --save이 가이드에서는 swagger-jsdoc 버전 5.0.1을 사용합니다. 최신 버전은 이 튜토리얼과 호환되지 않을 수 있습니다.
1.2 : API 사양 생성
Swagger UI는 OpenAPI 정의 세트에서 문서 페이지를 작성합니다. 이러한 정의는 REST API를 설명하기 위해 YAML 또는 JSON으로 작성됩니다. OpenAPI 사양의 기본 구조에 대한 자세한 내용은 기본 구조를 참조하세요.
Express API의 app.js 파일에서 필수 모듈 목록 아래에 다음 코드를 추가하십시오.
// app.js
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerDefinition = {
openapi: '3.0.0',
info: {
title: 'Express API for JSONPlaceholder',
version: '1.0.0',
},
};
const options = {
swaggerDefinition,
// Paths to files containing OpenAPI definitions
apis: ['./routes/*.js'],
};
const swaggerSpec = swaggerJSDoc(options);swaggerDefinition 객체 (즉, OpenAPI 정의)는 API의 루트 정보를 정의합니다. API의 제목 및 버전과 같은 몇 가지 기본 정보를 swaggerDefinition에 제공하십시오. 나중에 더 입력 할 수 있습니다.
옵션 객체에는 이 swaggerDefinition 객체와 api라는 경로 배열이 포함됩니다. 다른 OpenAPI 정의를 포함하는 파일의 경로입니다. 이러한 파일 경로는 Express API의 루트 디렉토리에 상대적이어야 합니다. 우리의 경우 정의는 / routes 파일의 JSDoc에 직접 작성됩니다. 위에 표시된 대로 파일 이름을 개별적으로 나열하거나 와일드 카드 구분 기호 *를 사용하여 디렉토리에 있는 모든 JavaScript 파일을 추가 할 수 있습니다.
옵션 객체는 swagger-jsdoc에서 swaggerSpec이라는 변수에서 OpenAPI 사양을 생성하는 데 사용됩니다. 이 사양은 문서 페이지를 만들기 위해 Swagger UI에서 일반적으로 사용하는 swagger.json 또는 swagger.yaml 파일과 동일합니다. 다음 단계에서 이 개체를 Swagger UI에 전달합니다.
오류가 없는지 확인하려면 Express 서버를 다시 시작하십시오. 이 단계에서 오류가 발생하면 swagger-jsdoc 버전이 정확히 5.0.1인지 확인하십시오.
1.3 : Swagger UI 문서 페이지 만들기
Express API 용 Swagger UI 페이지를 만들려면 app.js 파일에 swagger-ui-express를 포함합니다. 그런 다음 / docs (또는 원하는 이름)라는 엔드 포인트 경로를 추가합니다.
// app.js
// ...
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
// ...
var app = express();
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));위에 표시된 대로 swagger-ui-express는 엔드 포인트를 설정하기 위한 두 개의 콜백을 제공합니다. 하나는 swaggerSpec 정의로 Swagger UI를 설정하는 콜백이고 다른 하나는 / docs 엔드 포인트에 제공하는 콜백입니다.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 이동합니다.
Express API의 제목 및 버전 번호와 OpenAPI 버전 번호 (3.0.0)가 표시됩니다. 아직 다른 정의가 없기 때문에 "사양에 정의 된 작업이 없습니다!"라는 메시지가 표시됩니다. 메시지:
이제 API에 대한 멋진 문서 페이지가 시작되었습니다! 이 자습서의 나머지 부분에서는 OpenAPI 정의에 대한 기본 소개를 제공합니다.
2 단계 : API의 루트 정보 정의
Swagger UI 문서 페이지를 만들었고 문서 작성을 시작할 준비가 되었습니다. 그러나 먼저 API에 대한 더 많은 루트 정의를 추가해야 합니다.
app.js로 돌아갑니다. 정보 개체는 OpenAPI의 정보 개체에 매핑 되어 제목, 설명, 서버 목록, 연락처 정보 및 API 경로 목록을 정의합니다.
다음은 보다 완전한 정의의 예입니다.
// app.js
const swaggerDefinition = {
openapi: '3.0.0',
info: {
title: 'Express API for JSONPlaceholder',
version: '1.0.0',
description:
'This is a REST API application made with Express. It retrieves data from JSONPlaceholder.',
license: {
name: 'Licensed Under MIT',
url: 'https://spdx.org/licenses/MIT.html',
},
contact: {
name: 'JSONPlaceholder',
url: 'https://jsonplaceholder.typicode.com',
},
},
servers: [
{
url: 'http://localhost:3000',
description: 'Development server',
},
],
};프로덕션 서버가 있는 경우 서버 목록에 URL과 설명을 추가하십시오. 루트 정의에 추가 할 수 있는 다른 속성에 대한 자세한 내용은 기본 구조를 참조하십시오.
OpenAPI 문서에서 경로 필드도 있음을 알 수 있습니다. 각 경로는 JSDoc 주석 (다음 단계에서 추가)에 개별적으로 정의되므로 여기에서 경로 정의를 지정할 필요가 없습니다. 이러한 경로 정의는 swagger-jsdoc에 의해 경로 객체로 컴파일 됩니다.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 문서 페이지 상단에 API에 대한 자세한 정보가 표시 되어야 합니다.
이제 Express 경로 문서화를 시작할 수 있습니다.
3 단계 : 문서 작성
/docs 엔드 포인트에서 사용 가능한 Swagger UI 문서 페이지와 API의 전체 루트 정보 세트를 사용하여 경로 정의 작성을 시작할 수 있습니다. 각 경로 정의는 API의 Express 경로에 해당합니다. GET /users 및 DELETE /users /:id와 같은 작업 및 끝점 경로를 모두 설명합니다.
3.1 : 경로 문서화
/routes/users.js를 문서화하려면 먼저 첫 번째 경로 위에 @swagger로 시작하는 주석을 추가하십시오. 경로에 대한 몇 가지 기본 정보와 함께 다음을 따르십시오.
// routes/users.js
/**
* @swagger
* /users:
* get:
* summary: Retrieve a list of JSONPlaceholder users
* description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
*/
router.get('/', function(req, res) {
//...
});swagger-jsdoc은 @swagger 또는 @openapi 태그가있는 주석을 찾아 OpenAPI 정의를 생성합니다.
코드 예제에 표시된 대로 엔드 포인트 경로 / users 및 작업 get (두 공백 들여 쓰기)을 추가하십시오. Express 라우터 함수 get ( '/')의 경로는 / users에 상대적이므로 정의의 경로는 / users 여야 합니다.
요약은 이 경로의 목표에 대한 간략한 설명이어야 합니다. 설명은 경로를 사용하려는 시기 또는 이유와 같은 더 자세한 정보를 제공해야 합니다.
들여 쓰기에는 탭이 아닌 2 개의 공백 (또는 4 개의 공백)을 사용해야 합니다. 자세한 내용은 YAML 구문을 참조하세요.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 페이지 하단에 GET / users 목록이 표시되어야 합니다.
3.2 : 문서 응답
사용자는 이 GET 요청이 성공할 때 (즉, 상태 코드 200) 반환 되는 내용을 알고 싶어합니다. 성공적인 응답을 정의하려면 응답 객체와 200이라는 응답을 경로 정의에 추가합니다.
// routes/users.js
/**
* @swagger
* /users:
* get:
* summary: Retrieve a list of JSONPlaceholder users.
* description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
* responses:
* 200:
* description: A list of users.
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: array
* items:
* type: object
* properties:
* id:
* type: integer
* description: The user ID.
* example: 0
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
*/
router.get('/', function(req, res) {
//...
});설명 필드는 응답 또는 반환 되는 내용을 설명합니다. 콘텐츠 필드는 콘텐츠 유형 (application / json)을 설명하고 스키마는 응답 개체를 설명합니다. 이 경우 JSONPlaceholder는 요청한 데이터가 포함 된 데이터 필드가 있는 개체를 반환합니다. 이 응답의 경우 데이터에는 사용자 개체의 배열이 포함됩니다. 지금은 파일이 복잡해지지 않도록 하나 또는 두 개의 사용자 속성 (예 : ID 및 이름)을 추가합니다.
각 속성에 대한 실제 예제 값을 추가합니다 (예 : 'Leanne Graham'). 그렇지 않으면 Swagger UI는 '문자열'과 같은 일반적인 예를 만듭니다.
이 스키마에서 유형이 어떻게 정의되는지 확인하십시오. 예를 들어 배열을 정의하려면 type : array 및 items 필드를 추가하십시오. 데이터 유형 문서에서 유형에 대해 자세히 알아보세요.
이 방법으로 오류 응답을 설명 할 수도 있습니다. 각 응답을 설명하는 데 사용할 수 있는 필드에 대한 자세한 내용은 Swagger의 응답 설명 문서를 참조하세요.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 응답, 예제 값 (각 속성에 대해 제공 한 예제 값 사용),이 응답에서 반환 된 데이터의 스키마가 표시되어야 합니다.
다음으로 이미 다룬 필드 (요약, 설명 및 응답)를 추가하여 GET / users / : id 경로를 정의합니다.
// routes/users.js
/**
* @swagger
* /users/:id:
* get:
* summary: Retrieve a single JSONPlaceholder user.
* description: Retrieve a single JSONPlaceholder user. Can be used to populate a user profile when prototyping or testing an API.
* responses:
* 200:
* description: A single user.
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: object
* properties:
* id:
* type: integer
* description: The user ID.
* example: 0
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
*/
router.get('/:id', function(req, res) {
//...
});경로 매개 변수 (id)가 엔드 포인트 경로 : / users / : id에 추가됩니다. 콜론 (:) 또는 중괄호 ({})를 사용하여 엔드 포인트 경로에서 경로 매개 변수를 표시하십시오.
스키마의 데이터 개체는 사용자 개체의 배열 대신 단일 사용자 개체를 포함하지만 속성은 동일합니다.
다음으로 이미 다룬 필드 (요약, 설명 및 응답)를 추가하여 POST / 사용자를 정의합니다.
// routes/users.js
/**
* @swagger
* /users:
* post:
* summary: Create a JSONPlaceholder user.
* responses:
* 201:
* description: Created
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: object
* properties:
* id:
* type: integer
* description: The user ID.
* example: 0
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
*/
router.post('/', function(req, res) {
// ...
});이 경우 성공적인 응답은 201입니다. 새 사용자가 포함 된 데이터 필드가 있는 개체를 반환합니다.
동일한 방법으로 나머지 경로에 대한 경로 정의를 계속 추가 할 수 있습니다. 이후 단계에서 몇 가지 리팩토링을 수행 할 것입니다.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 이제 GET / users / : id, POST / users 및 추가 한 기타 경로 정의에 대한 목록이 표시됩니다.
3.3 : 요청 문서화
매개 변수 및 요청 본문과 같은 요청 데이터도 OpenAPI 정의에 문서화 할 수 있습니다. 예를 들어, GET / users / : id에는 문서화 해야 하는 id 매개 변수가 있습니다.
매개 변수를 문서화하려면 경로 정의에 매개 변수 필드를 추가하십시오.
// routes/users.js
/**
* @swagger
* /users/:id:
* get:
* summary: Retrieve a single JSONPlaceholder user.
* description: Retrieve a single JSONPlaceholder user. Can be used to populate a user profile when prototyping or testing an API.
* parameters:
* - in: path
* name: id
* required: true
* description: Numeric ID of the user to retrieve.
* schema:
* type: integer
* responses:
* 200:
* ...
*/
router.get('/:id', function(req, res) {
//...
});
이 매개 변수에 대한 정의에서 in은 매개 변수의 위치를 정의합니다 (이 경우 경로의 일부이므로 경로 매개 변수입니다). 이름, 설명 및 스키마와 매개 변수의 필수 여부를 추가 할 수도 있습니다. 자세한 내용은 매개 변수 설명을 참조하십시오.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 이 경로에 대한 매개 변수 목록이 표시됩니다.
다음으로 POST / users에 대한 요청 본문을 문서화하여 데이터베이스에서 새 사용자를 만드는 데 필요한 데이터를 설명합니다. 이렇게 하려면 다음 경로 정의에 requestBody 필드를 추가합니다.
// routes/users.js
/**
* @swagger
* /users:
* post:
* summary: Create a JSONPlaceholder user.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
* responses:
* 201:
* ...
*/
router.post('/', function(req, res) {
// ...
});그러면 이 경로 정의에 요청 본문 스키마가 추가됩니다. 이 예는 이름이 요청 본문에 전송 될 수 있음을 보여줍니다. 나중에 새 사용자에 대한 속성을 더 추가 할 수 있습니다. 자세한 내용은 요청 본문 설명을 참조하세요.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 제공 한 스키마가 포함 된 요청 본문이라는 섹션이 표시됩니다.
3.4 : 리소스 문서화
지금까지 문서에서 사용자 스키마를 여러 번 반복했음을 알 수 있습니다. 이러한 중복을 방지하기 위해 한 곳에서 사용자 스키마를 정의하고 다른 곳에서 참조 할 수 있습니다.
Express API에서 정의한 각 모델은 스키마 정의 (또는 구성 요소)로 별도로 문서화 할 수 있습니다. 사용자 모델에 대해 이를 수행하려면 파일 상단의 구성 요소 / 스키마 아래에 사용자 스키마 정의를 추가하십시오.
* components:
* schemas:
* User:
* type: object
* properties:
* id:
* type: integer
* description: The user ID.
* example: 0
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
*/그런 다음 $ref를 사용하여 이 스키마 정의를 참조 할 수 있습니다.
// routes/users.js
/**
* @swagger
* /users:
* get:
* summary: Retrieve a list of JSONPlaceholder users
* description: Retrieve a list of users from JSONPlaceholder. Can be used to populate a list of fake users when prototyping or testing an API.
* responses:
* 200:
* description: A list of users.
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
router.get('/', function(req, res) {
//...
});$ref 경로는 JSON 참조 표기법을 사용합니다. #symbol는 현재 문서의 루트를 나타내며 나머지 중첩 값은 순서대로 해결됩니다. 자세한 내용은 $ref 사용을 참조하십시오.
Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. 이제 경로 정의에서 이 사용자 스키마를 사용하고 페이지 하단에 사용자에 대한 스키마 정의가 표시됩니다.
마찬가지로 POST / users 요청 본문에서 참조 할 NewUser 개체를 정의 할 수 있습니다. 사용자 스키마의 일부 필드를 포함하지만 전부는 아니므로 $ ref를 사용하여 둘 사이의 중복을 방지 할 수도 있습니다.
/**
* @swagger
* components:
* schemas:
* NewUser:
* type: object
* properties:
* name:
* type: string
* description: The user's name.
* example: Leanne Graham
* User:
* allOf:
* - type: object
* properties:
* id:
* type: integer
* description: The user ID.
* example: 0
* - $ref: '#/components/schemas/NewUser'
*/allOf 키워드는 모델 정의,이 경우 NewUser 정의 (이름 속성 포함)와 id 속성이 있는 개체를 결합합니다. 자세한 내용은 oneOf, anyOf, allOf를 참조하십시오.
이제 POST / users에 대한 요청 본문 정의에서 NewUser를 참조 할 수 있습니다.
/**
* @swagger
* /users:
* post:
* summary: Create a JSONPlaceholder user.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/NewUser'
* responses:
* 201:
* ...
*/
router.post('/', function(req, res) {
// ...
});Express 서버를 다시 시작하고 브라우저에서 localhost : 3000 / docs로 다시 이동합니다. POST / users에 대한 요청 본문 정의에 NewUser 스키마가 표시됩니다.
이것은 JSDoc 주석에서 OpenAPI 정의를 생성하는 기본 기술을 다룹니다.
결론
이제 Express API에 대한 완전한 참조 문서 페이지를 생성하도록 설정되었습니다. OpenAPI 정의의 기본 세트와 이를 표시하는 Swagger UI 페이지를 작성했습니다. OpenAPI 사양으로 더 많은 연습을 원하면 jsonplaceholder-express-api 문서화를 완료 할 수 있습니다.
이 자습서에서는 OpenAPI 정의 작성의 기본 사항도 다루었습니다. 문서를 완성하려면 OpenAPI 사양 및 Swagger 문서를 참조하십시오.
이 자습서 중에 추가 된 모든 코드를 포함하는 jsonplaceholder-express-api 버전을 보려면 저장소의 문서 분기를 참조하세요.
등록된 댓글이 없습니다.
