swagger_-_napisannja_dokumentaciji [wiki.hostingcloud.com.ua]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Swagger ======
[[https://swagger.io/|swagger - написання документації]]

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

===== Бібліотека redocly/cli =====
* Для зручної роботи зі Swagger ми скористаємося бібліотекою @redocly/cli
<code>
npm i -D @redocly/cli
</code>
Для роботи з документацією ми одразу можемо додати відповідні зміни у поле scripts в package.json:
<code>
// package.json

{

/* Інший код файлу */

	"scripts": {
		"build": "npm run build-docs",
    "build-docs": "redocly bundle --ext json -o docs/swagger.json",
    "preview-docs": "redocly preview-docs",
   }
}

</code>
  * Команда preview-docs допоможе нам писати документацію з hot-reload, тобто з гарячим перезавантаженням сторінки при внесенні змін(як в nodemon). Більш детально можете прочитати про це за [[https://redocly.com/docs/cli/commands/preview-docs|посиланням]]
  * Команда build-docs буде формувати один файл із розширенням .json за шляхом docs/swagger.json. Відповідно, нам треба створити таку папку з файлом, де у файл ми запишемо порожній обʼєкт:

<code>
// docs/swagger.json

{}

</code>

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

<code>
# 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

</code>
В цьому файлі ми бачимо, що нам треба створити ще файли docs/index.html та docs/openapi.yaml. Створимо їх з наступним вмістом
<code>
<!-- 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>
</code>
<code>
# 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


</code>
===== Бібліотека Swagger UI Express для публікації документаціїї swagger на сервері =====
[[https://www.npmjs.com/package/swagger-ui-express|Swagger UI Express - публікації документаціїї ]]


===== Розширення для VSCode Redocly OpenAPI: =====
Також перед початком написання документації ми радимо вам встановити розширення у VSCOde [[https://marketplace.visualstudio.com/items?itemName=Redocly.openapi-vs-code|Redocly OpenAPI]]
===== Використання =====
==== preview ====
<code>
npm run preview-docs  
</code>
Перегляд попередньої збудованої сторінки буде доступний на **http://127.0.0.1:8080/**
Взагалі в терміналі треба читати - там пише на який порт і куди сервіс запуститься.