Documentando la API HTTP (y más) con Foliant

Hola Habr.

En este artículo, le hablaré sobre Foliant y las posibilidades de documentar la API HTTP usándolo. Me centraré en las API que se describen mediante OpenAPI/Swagger. También abordaré brevemente las capacidades de documentación de API descritas utilizando otras especificaciones.

Y para que le resulte más fácil comenzar, compartiré un enlace a un paquete de inicio que lo ayudará a crear rápidamente una referencia de API HTTP estática usando Foliant e implementarla en Gitlab Pages.

El artículo fue escrito en base a mi charla en la conferencia Techwriter Days #1, celebrada del 5 al 6 de abril de 2024. Esto no es una instrucción. Más bien, es una descripción general de las capacidades de Foliant y cómo usarlas al documentar las API.

Una de las formas de documentar la API HTTP son los libros de referencia en forma de sitios estáticos con descripciones generales, información de autorización, descripciones de métodos, ejemplos de solicitudes, respuestas y otra información.

Las ventajas de este tipo de documentación:

• Los sitios estáticos son fáciles de alojar. Son fáciles de gestionar.

• Cualquiera puede trabajar con el directorio: no es necesario ir a un stand con Swagger UI y activar allí algunos identificadores de API (después de todo, el acceso a dichos stands no siempre está disponible).

• En un sitio de este tipo puede publicar toda la información necesaria sobre la API e incluso más de la que está disponible, por ejemplo, en la especificación OpenAPI.

La preparación de dichos libros de referencia, por regla general, recae sobre los hombros de un redactor técnico (o de un redactor técnico que trabaja en conjunto con DevOps o DocOps).

Y aquí puede enfrentarse a algunos “desafíos”:

• Un sistema puede tener muchos componentes (microservicios).

• Todos estos componentes tienen su propia API. O, en general, el sistema puede tener varias API para diferentes “consumidores” externos.

• Cada equipo de desarrollo describe las especificaciones API de manera diferente: simplemente hay especificaciones o especificaciones técnicas para el desarrollo, hay OpenAPI, RAML u otra especificación, o simplemente hay comentarios en el código.

Al mismo tiempo, en la mayoría de los casos, todo el mundo quiere ver referencias fáciles de leer para todas las API HTTP con las que tienen que interactuar.

Y alguien más quiere ver la documentación en diferentes formatos: no solo en forma de sitio de referencia, sino también en PDF y DOCX.

¿Qué hacer como redactor técnico?

Por supuesto, nos gustaría encontrar una herramienta que nos permitiera crear libros de referencia uniformes y convenientes, independientemente de los datos que tengamos como fuente.

Y existe tal herramienta. Este – Elogio.

¿Qué es foliante?

Foliant es un sistema de publicación para la creación de documentación en diferentes formatos (sitio estático, PDF, documentos de Word, etc.) compatible con el principio de fuente única.

Esta es una herramienta de código abierto de “alto nivel”. Internamente, utiliza otras herramientas de código abierto para generar documentación (en Foliant se les llama “backends”). En particular, los SSG (generadores de sitios estáticos) se utilizan como backends, que reciben archivos de rebajas como entrada y producen documentación en forma de sitios estáticos.

La imagen de arriba muestra el diagrama más simplificado de la arquitectura Foliant. Aquí vemos el kernel, la capa de configuración, los backends y los preprocesadores. En el contexto de este artículo, nos interesan principalmente los backends y los preprocesadores. No profundizaremos más.

Backends foliantes

Los backends son herramientas de código abierto que reciben archivos de rebajas como entrada y producen documentación en el formato requerido.

Ejemplos de backends que se utilizan en Foliant:

• MkDocs: para generar portales con documentación.

• Pandoc: para generar documentación en formato PDF o DOCX.

• Slate: para generar sitios de directorio de bases de datos y API.

No solo por backends

Una de las características principales de Foliant son los preprocesadores. Se ejecutan delante de los backends y procesan archivos de cierta manera para que sean comprensibles para esos mismos backends.

Los preprocesadores pueden realizar diferentes tareas. Por ejemplo:

• Convierta datos de un formato a otro (en particular, a Markdown, que es comprensible para los servidores).

• Dibujar diagramas (la entrada del preprocesador es código en una notación determinada, la salida es una imagen).

• Incluye información de varios archivos en uno.

• Administre el diseño y el formato en archivos Markdown que se enviarán a los servidores.

A continuación se muestran varios ejemplos de preprocesadores y una descripción de sus capacidades.

Cómo documentar la API HTTP con Foliant

Para documentar la API HTTP, Foliant utiliza el backend de Slate (no solo eso, sino que aquí estoy hablando específicamente de Slate). Genera referencias de bases de datos y API como sitios estáticos de una sola página.

Slate acepta archivos Markdown como entrada y genera archivos estáticos (HTML, CSS, JS) como salida.

Este backend admite resaltado de sintaxis para más de 100 idiomas. Los sitios resultan convenientes, con un diseño limpio e intuitivo.

Con Foliant y Slate, puede crear diferentes flujos para generar directorios, según la información de entrada que esté disponible a través de la API HTTP. A continuación se muestra una descripción de varios casos y el flujo que se puede construir para implementarlos.

Si el proyecto tiene Swagger (especificación OpenAPI)

En este caso, utilizando “Foliant” puede crear el siguiente flujo para crear un directorio API:

1. Tomemos la especificación.

2. Lo procesamos con el preprocesador SwaggerDoc. Convierte la especificación en Markdown, que el backend puede entender.

3. Enviamos el resultado a Slate y el resultado es un bonito directorio de una página.

La figura muestra un ejemplo de cómo se vería un sitio Slate con la configuración predeterminada (más información sobre cómo personalizar dicho sitio a continuación).

Como especificación, tomé la conocida, si no para todos, pero para muchos, la especificación de API de Petstore.

Con este flujo, la mayor parte del trabajo lo realiza el preprocesador SwaggerDoc. Toma la especificación OpenAPI y la convierte en Markdown, que Slate entiende.

Puede reenviarle la especificación OpenAPI en diferentes formatos y de diferentes maneras:

• en formato JSON,

• en formato YAML,

• ubicado localmente,

• yaciendo en algún lugar del servidor, en un repositorio, algún tipo de almacenamiento, etc.

Si el proyecto no tiene Swagger (especificación OpenAPI)

En este caso, el flujo se verá así:

Con este flujo, el redactor técnico:

1. Prepara descripciones manualmente en Markdown. Se puede tomar información: de descripciones de métodos del proyecto, realizar solicitudes a la API usted mismo y agregar la información recibida a un archivo md, recibirla de desarrolladores, analistas y otras partes interesadas. El archivo de rebajas se formatea de acuerdo con ciertas reglas para que sea comprensible para el servidor.

2. “Alimenta” el archivo de rebajas al backend de Slate y produce un sitio de directorio de una página como salida.

A continuación se muestra un ejemplo del diseño de dicho archivo Markdown que describe los métodos API:

# Introduction

Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database.

# Authentication

> To authorize, use this code:

```shell
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: meowmeowmeow"
```

### HTTP Request

`GET 

### Query Parameters

Parameter | Default | Description
--------- | ------- | -----------
include_cats | false | If set to true, the result will also include cats.

Aquí:

• El encabezado de primer nivel se utiliza para indicar el nombre de un grupo de métodos.

• Los títulos de segundo nivel son para los nombres de grupos y métodos.

• Lo que indica el signo > y como bloque de código (``` ```) va a la sección derecha del sitio, donde hay ejemplos de código.

De lo contrario, aquí se utiliza la sintaxis familiar de Markdown: se admiten tablas, enlaces, etc. Se pueden encontrar más detalles sobre la sintaxis en Pizarra Wiki.

Aquellos. en este caso, cuando no existe una especificación Swagger, no existe un vínculo como el preprocesador SwaggerDoc. Después de todo, ya tenemos un archivo de rebajas que Slate entenderá y podrá “alimentarle” directamente.

Si necesita agregar información sobre varias API a un directorio

Si su sistema tiene muchos componentes (microservicios) y los usuarios necesitan información sobre ellos en un libro de referencia, Foliant lo ayudará a implementarlo. Además, algunos componentes pueden tener Swagger y otros no. En este caso, deberá combinar los enfoques discutidos anteriormente:

En un archivo de rebajas, puede escribir una descripción que Slate pueda entender manualmente. En otro, puede colocar una descripción que se analizó a partir de los comentarios en el código (el proceso de análisis y creación de dichos sitios es un tema aparte). También puede agregar un archivo md con una o más etiquetas de preprocesador SwaggerDoc.

Todo se pegará en un solo todo y será procesado por el backend de Slate. El resultado será un directorio de sitios que contendrá una descripción de varias API a la vez.

Si tiene otros “deseos” de referencias de API

Por supuesto, no todo se limita a los casos descritos anteriormente. Las situaciones y “deseos” de los usuarios del directorio API pueden ser diferentes. Y aquí se revela todo el poder de Foliant en la forma de sus preprocesadores. A continuación se muestra una breve descripción de varios de ellos. Puede encontrar más información sobre todos los preprocesadores y sus capacidades en la documentación de Foliant.

Reemplazo de preprocesador

Ayudará en diferentes casos. Por ejemplo:

• Cuando necesita agregar datos realistas en lugar de respuestas de ejemplo “impersonales” para un método. O, por ejemplo, desea agregar explicaciones directamente a la respuesta de ejemplo.

• Si necesita cambiar la descripción de un método al compilar un libro de referencia, ampliar algún fragmento de texto o eliminarlo por completo (útil, por ejemplo, cuando un especialista técnico no tiene acceso al código de donde provienen las fuentes).

• Cuando necesite corregir un ensamblaje de libro de referencia torcido (puede agregar HTML y CSS usando este preprocesador).

Reemplazar admite expresiones regulares. Este preprocesador “revisa” los archivos Markdown antes de enviarlos a Slate y reemplaza algunos fragmentos de texto por otros.

Ejemplo de configuración del preprocesador:

- replace:
	re_dictionary:
		'`(?i)(my_api)`': '(\1)(
		'`(?i)(my_site)`': '(\1)(https:// www.my_site.ru)'

API de preprocesadorReferencias

Será útil si necesita agregar enlaces a otros directorios al libro de referencia de API. Aquí se utiliza una determinada sintaxis: basta con especificar el método y el prefijo del directorio en el que se encuentra en el formato My-API: GET /user/statusy el enlace se generará cuando se cree el sitio.

Ejemplo de configuración del preprocesador:

PET-API:
      mode: find_by_tag_content
      url:  # адрес справочника API
      content_template: 'Operation {verb} {command}’

Preprocesadores para trabajar con gráficos.

Foliant tiene varios preprocesadores que se pueden usar para agregar gráficos a sitios de referencia API. Éstos son algunos de ellos:

• plantuml,

• Sirena,

• Graphviz.

Convierten código en la notación apropiada en imágenes.

Código de muestra para el preprocesador Plantuml:

@startuml

skinparam componentStyle rectangle

(Препроцессор\n SwaggerDoc) -> (Slate) : Markdown
(Markdown) --> (Slate) : Markdown
(Парсер)-->(Markdown)
(Исходники в Markdown) --> (Slate) : Markdown
(Slate) -> (Сайт) : HTML, CSS, JavaScript

@enduml

Incluye preprocesador

Será útil si necesita agregar fragmentos de otros archivos a las referencias de API. Puede insertar archivos completos, o algunas partes de ellos, especificando, por ejemplo, los encabezados entre los cuales se tomará e insertará el texto, o la identificación de los elementos HTML.

Ejemplo de uso de un preprocesador:

<!-- Вставка файла целиком -->

Ниже — текст из другого файла.
<include src="

<!-- Вставка файла из другого репозитория -->
Ниже — текст из другого репозитория.
<include url="

En total, Foliant cuenta con más de 45 preprocesadores para diferentes necesidades. Además, puedes agregar aquí tus propios preprocesadores, para algunas necesidades específicas: la herramienta es de código abierto. Las instrucciones están en el sitio web del folio, claras y cómodas, con un ejemplo específico.

Personalización de directorios API

Puede influir en la apariencia del sitio a través de la configuración del preprocesador SwaggerDoc o el backend de Slate.

Debajo del capó, SwaggerDoc tiene la herramienta Widdershins, que procesa la especificación OpenAPI y produce archivos de rebajas. En realidad, no se puede influir en la apariencia del sitio, sino en el orden en que se muestran los bloques de información configurando las plantillas de Widdershins. Usan la sintaxis .dot.

La diapositiva muestra un ejemplo de cómo se cambió ligeramente la plantilla estándar del repositorio de Widdershins (en particular, se reemplazó el idioma inglés por el ruso, se cambió el orden de visualización de la información, etc.) y se obtuvo un sitio de directorio ligeramente personalizado.

En cuanto a la personalización a través de Slate, puede enviarle CSS y JS personalizados, por ejemplo:

• cambiar el logotipo;

• cambiar combinación de colores;

• agregue algún tipo de interactividad al sitio (por ejemplo, conecte Prism.js y análogos), adjunte un contador de visitas o agregue autorización a través de JS con procesamiento en algún lugar de un servicio de terceros.

En general, puedes aprovechar al máximo CSS y JS si eres bueno en ello. Puede hacer casi cualquier cosa con el sitio y generar directorios API con cualquier apariencia y estructura.

Lo que necesitas para crear referencias de API usando Foliant

Foliant puede instalarse en su sistema o usarse en Docker. A continuación se muestra un ejemplo del proceso de compilación utilizando Docker como ejemplo.

Un proyecto típico que se utiliza para crear la referencia de API en Docker tiene este aspecto:

Contiene los elementos:

• src es una carpeta con archivos fuente que se utilizan durante el ensamblaje. Aquí es donde colocamos los archivos escritos a mano o aquellos con etiquetas de preprocesador SwaggerDoc.

• Archivo Docker y Docker-compose.

• Archivo de configuración foliant.yaml. Aquí se indican todas las configuraciones de ensamblaje: se enumeran los archivos a partir de los cuales se compilará el libro de referencia, se indican los preprocesadores y sus configuraciones, se configuran los backends, etc.

Ejemplo foliant.yaml:

title: slate_site

chapters:
  - api_from_json.md

preprocessors:
    - swaggerdoc:
        spec_path: pet_swagger.json
        mode: widdershins
        environment:
            language_tabs:
                - shell
                - java
            user_templates: !path ./widdershins_templates
    - includes

backend_config:
    slate:
        slug: API
        shards: 
        - !path ./slate_shards/basic

Es conveniente cuando las configuraciones de todos los preprocesadores y backends en Foliant se colocan en un solo archivo. Si lo deseas, puedes separarlos en archivos separados.

Cómo y dónde recopilar referencias de API

Aquí todo depende de tu imaginación, habilidades y recursos.

La opción más primitiva (o sencilla) es montar un sitio web localmente a mano y luego subirlo a algún lugar del hosting.

Puede configurar la compilación y carga automática de artefactos al público en GitLab o GitHub. Además, esto se puede automatizar: si utiliza una especificación de un repositorio de código, puede agregar un activador a su canalización, que iniciará la canalización en su repositorio con un muelle cuando ocurra algún evento en el repositorio de código “principal”. .

Puedes automatizar esto aún más para que todo suceda en algún servidor remoto. Por ejemplo, después de fusionar/insertar master, se inicia un ejecutor en el servidor, que inicia el procedimiento de compilación: el repositorio se clona en el servidor, el sitio se ensambla allí y se carga en la carpeta desde la cual se encuentra el dominio con la documentación. resuelto.

No sólo OpenAPI (Swagger)

Por cierto, Foliant no se limita a compilar libros de referencia a partir de especificaciones OpenAPI. Existe un preprocesador para trabajar con especificaciones en formato RAML. También hay un backend que recopila referencias de API a partir de especificaciones en formato Blueprint. Se llama Aglio.

Además, utilizando el mismo Slate, puede recopilar libros de referencia sobre GRPC-API. Para ello, por ejemplo, es adecuada la herramienta proto2slate.

Está claro que el Folio tiene que ver con la flexibilidad. Esta es una herramienta que permitirá a los techpis (o techpis-docops) no confundirse en diferentes situaciones e incluso combinar con éxito diferentes flujos para generar documentación API, creando referencias API agradables y fáciles de usar para los usuarios.

Como prometí, doy mi promesa. enlace al paquete de inicio para construir la referencia de API usando Foliant.