Генерация одностраничной статической документации из Swagger JSON: методы и примеры кода - Fcodenotes

Swagger – популярная платформа для проектирования, создания и документирования API. Он предоставляет формат спецификации на основе JSON, называемый Swagger JSON, который описывает структуру и поведение API. В этой статье мы рассмотрим различные методы создания одностраничной статической документации из Swagger JSON, а также примеры кода. Этот тип документации полезен для предоставления разработчикам и потребителям полного обзора вашего API.

Метод 1: пользовательский интерфейс Swagger
Пользовательский интерфейс Swagger — популярный инструмент для визуализации и взаимодействия с Swagger JSON. Он поддерживает создание одностраничной статической документации путем простого предоставления файла Swagger JSON. Чтобы использовать пользовательский интерфейс Swagger, выполните следующие действия:

Установить интерфейс Swagger:
```
npm install swagger-ui-dist
```

Создайте HTML-файл, например, index.html, и добавьте следующий код:

<!DOCTYPE html>
<html>
<head>
 <title>API Documentation</title>
 <link
   rel="stylesheet"
   type="text/css"
   href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css"
 />
</head>
<body>
 <div id="swagger-ui"></div>
 <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
 <script>
   window.onload = function () {
     SwaggerUIBundle({
       url: "path/to/your/swagger.json",
       dom_id: "#swagger-ui",
     });
   };
 </script>
</body>
</html>

Замените "path/to/your/swagger.json"фактическим путем к файлу Swagger JSON.
Откройте index.htmlв веб-браузере, и вы увидите созданную документацию.

Метод 2: ReDoc
ReDoc — еще один популярный инструмент для создания статической документации из Swagger JSON. Основное внимание уделяется простоте и читабельности. Вот как вы можете использовать ReDoc:

Установить ReDoc:
```
npm install redoc-cli
```
Создать документацию:
```
npx redoc-cli bundle -o index.html path/to/your/swagger.json
```
Эта команда создает один HTML-файл с именем index.html, содержащий документацию.
Откройте index.htmlв веб-браузере, и вы увидите созданную документацию.

Метод 3: Slate
Slate — это настраиваемый генератор документации, который можно использовать для создания статической документации из Swagger JSON. Вот как использовать Slate:

Установить план:
```
npm install -g slate
```
Создайте новый проект Slate:
```
slate new my-docs
```

Замените содержимое source/index.html.mdна:

# My API Documentation
```json
include::./path/to/your/swagger.json[]

Составьте документацию:
```
cd my-docs
bundle exec middleman build
```
При этом создается статическая документация в каталоге build.
Откройте сгенерированные файлы HTML в веб-браузере, чтобы просмотреть документацию.

В этой статье мы рассмотрели три различных метода создания одностраничной статической документации из Swagger JSON. Вы можете использовать Swagger UI, ReDoc или Slate в зависимости от ваших предпочтений и требований. Эти инструменты предоставляют простой и эффективный способ представить документацию по API разработчикам и потребителям. Не забудьте настроить документацию в соответствии со своими потребностями и предоставить четкий и полный обзор вашего API.