Swagger

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

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

* Для зручної роботи зі 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