Swagger

swagger - написання документації

Swagger - це набір інструментів для розробки, документування та взаємодії з веб-сервісами на основі їх API (інтерфейсів програмування застосунків). Основний компонент Swagger - це Swagger UI, який дозволяє генерувати автоматичну документацію для веб-сервісу на основі специфікації OpenAPI (раніше відомої як Swagger Specification). Swagger дозволяє розробникам швидко розробляти, тестувати та взаємодіяти з API, а також надає зручний спосіб для документування API та його функціоналу. Завдяки Swagger, розробники можуть легко створювати, зберігати та редагувати специфікації API, а також докладно описувати всі доступні ендпоінти, параметри запитів та відповіді сервера.

Бібліотека redocly/cli

* Для зручної роботи зі Swagger ми скористаємося бібліотекою @redocly/cli

npm i -D @redocly/cli

Для роботи з документацією ми одразу можемо додати відповідні зміни у поле scripts в package.json:

// package.json
{
/* Інший код файлу */
"scripts": {
"build": "npm run build-docs",
"build-docs": "redocly bundle --ext json -o docs/swagger.json",
"preview-docs": "redocly preview-docs",
}
}

Команда preview-docs допоможе нам писати документацію з hot-reload, тобто з гарячим перезавантаженням сторінки при внесенні змін(як в nodemon). Більш детально можете прочитати про це за посиланням

Команда build-docs буде формувати один файл із розширенням .json за шляхом docs/swagger.json. Відповідно, нам треба створити таку папку з файлом, де у файл ми запишемо порожній обʼєкт:

// docs/swagger.json
{}

Для того, щоб працювати з redocly CLI, нам також треба створити файл redocly.yaml в корені проєкту. Цей файл містить конфігурацію для роботи з redocly CLI. Він дозволяє налаштовувати параметри генерації документації для API, включаючи налаштування стилів, шрифтів, тем тощо. За допомогою цього файлу ми можемо легко керувати параметрами проєкту без необхідності змінювати код.

# redocly.yaml
# See <https://redocly.com/docs/cli/configuration/> for more information.
apis:
sample@v1:
root: docs/openapi.yaml
extends:
- recommended
rules:
no-unused-components: error
theme:
openapi:
htmlTemplate: ./docs/index.html
theme:
colors:
primary:
main: '#32329f'
generateCodeSamples:
languages: # Array of language config objects; indicates in which languages to generate code samples.
- lang: curl
- lang: Node.js
- lang: JavaScript

В цьому файлі ми бачимо, що нам треба створити ще файли docs/index.html та docs/openapi.yaml. Створимо їх з наступним вмістом

<!-- docs/index.html -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>API Reference | ReDoc</title>
<!-- needed for adaptive design -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" href="favicon.png">
<!--
ReDoc uses font options from the parent element
So override default browser styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
{{{redocHead}}}
</head>
<body>
{{{redocHTML}}}
</body>
</html>
# docs/openapi.yaml
openapi: 3.1.0
info:
version: 1.0.0
title: Students app
license:
name: Apache 2.0
url: <http://www.apache.org/licenses/LICENSE-2.0.html>
description: >
This is a documentation of students app
tags:
- name: Students
description: Operations about users.
- name: Auth
description: Auth operations.
servers:
- url: <http://localhost:3000>
- url: <https://example.com/api/v1>
paths:
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer