Различия

Показаны различия между двумя версиями страницы.

--- swagger_-_napisannja_dokumentaciji [2024/06/27 17:00]
tro создано
+++ swagger_-_napisannja_dokumentaciji [2024/06/30 10:54] (текущий)
tro
@@ Строка 1: / Строка 1: @@
 ====== 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/**
+Взагалі в терміналі треба читати - там пише на який порт і куди сервіс запуститься.
-https://swagger.io/|swagger - написання документації