Redoc - инструмент для создания документации OpenAPI

Redoc - это инструмент для создания документации API, который использует спецификацию OpenAPI.

Redoc позволяет описывать свои эндпойнты, методы и параметры в формате OpenAPI, после чего генерирует красивую документацию, которая автоматически обновляется при изменении спецификации. Интерфейс, созданный Redoc, может быть либо встроенным в приложение, либо размещен на отдельной странице.

Пример:

Для начала, необходимо создать файл, в котором будут описаны ваше API и его эндпойнты в формате OpenAPI. Например:


openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      summary: Returns a list of users
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':
          description: A JSON array of user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer

Затем, необходимо установить библиотеку Redoc CLI:


npm install redoc-cli -g

После этого можно сгенерировать документацию:


redoc-cli bundle my-api.yaml

Будет сгенерирован файл `index.html`, который можно открыть в браузере и посмотреть документацию нашего API.

Кроме этого, Redoc имеет различные опции для настройки документации, такие как изменение цвета текста или задание своего логотипа. Например, загрузка логотипа:


redoc-cli bundle my-api.yaml --options.theme.logo.src=./logo.png

В результате мы получим документацию с нашим логотипом.

Также, можно интегрировать Redoc в свое приложение, используя `redoc-stencil`. Например, чтобы разместить документацию на странице веб-приложения:


import { Component, h } from '@stencil/core';
@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true
})
export class MyComponent {
  render() {
    return (
      
        
      
    );
  }
}

Это позволит встроить документацию прямо в приложение.

Таким образом, Redoc - это мощный инструмент для создания документации API, который упрощает задачу описания эндпойнтов и методов, а также генерирования красивой и удобной документации в виде HTML-страницы или встраиваемого компонента.

Redoc - инструмент для создания документации OpenAPI

Похожие вопросы на: "redoc "