Сборка API документации#
Подготовка к сборке#
Для успешной сборки и отображения API документации на сайте подготовьте репозиторий документации, как описано ниже:
Создайте папку apis и разместите в ней папки для каждого типа API. Например, если публичные API доступны для сервисов Service1 и Service2, создайте каталоги apis/service1-api и apis/service2-api.
Внутри каждого каталога создайте файл info.json с метаинформацией об API.
Разместите API документацию рядом с файлом info.json одним из следующих способов:
Вручную#
Разместите API документацию в репозитории документации в папке apis/ рядом с файлом info.json:
GRAPH_QL
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── graphql/ └── index.graphql // GraphQL API спецификацияGRPC
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── proto/ └── index.proto // gRPC API спецификацияJAVA
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── html/ ├── index.html // Корневой HTML файл Javadoc └── ... // Остальные статичные файлы JavadocJSON_RPC
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── json/ └── index.json // JSON-RPC API спецификация (в соответствии с OpenRPC)KAFKA
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── json/ └── index.json // Kafka API спецификация (в соответствии с AsyncAPI)MQ
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── json/ └── index.json // MQ API спецификация (в соответствии с AsyncAPI)OTHER
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── html/ ├── index.html // Корневой HTML файл прочей документации └── ... // Дополнительные файлы прочей документации при их наличииREST
apis/ // Директория с документацией на публичные API └── <api-name>/ // Директория с документацией на версию публичного API ├── info.json // Метаинформация об API └── json/ └── index.json // REST API спецификация (в соответствии с OpenAPI)
Из Git#
Укажите в apis/<api-name>/info.json в блоке repo информацию о репозитории, из которого нужно собрать API документацию. Для успешной настройки в репозитории в папке repo.apidir должен находиться соответствующий файл:
GRAPH_QL
index.graphql или <любое-имя>.graphql, если он является единственным файлом с расширением .graphql в папке.
GRPC
index.proto или <любое-имя>.proto, если он является единственным файлом с расширением .proto в папке.
JAVA
pom.xml. В pom.xml должен быть добавлен плагин maven-javadoc-plugin.
В GetDocs команда запуска javadoc зависит от pom.xml:
Если проект является агрегирующим (в pom.xml есть элемент
<modules>) и версия maven-javadoc-plugin 3.1.0 или выше:mvn javadoc:aggregate-no-fork -Dadditionalparam=-Xdoclint:none -Ddoclint=noneВ ином случае:
mvn javadoc:javadoc-no-fork -Dadditionalparam=-Xdoclint:none -Ddoclint=none
Для сборки используется Java 17, поэтому в итоге получается Javadoc с поиском, а не с боковым меню.
JSON_RPC
index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.
KAFKA
index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.
MQ
index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.
OTHER
index.html
REST
index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.
Из Nexus CI#
Укажите в apis/<api-name>/info.json в блоке gav координаты (GroupId, ArtifactId, Version) API документации (при этом блок repo в info.json должен отсутствовать):
GRAPH_QL
В хранилище артефактов описание GraphQL API должно быть представлено артефактом (текстовый файл) типа graphql (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:graphql).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).GRPC
В хранилище артефактов описание gRPC API должно быть представлено артефактом (текстовый файл) типа proto (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:proto).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).JAVA
В хранилище артефактов документация на публичные Java API должна быть представлена артефактом типа jar (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:jar,classifier:javadoc).JSON_RPC
В хранилище артефактов описание JSON-RPC API должно быть представлено артефактом типа json (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:json).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).KAFKA
В хранилище артефактов описание Message Broker API должно быть представлено артефактом типа json (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:json).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).MQ
В хранилище артефактов описание Message Broker API должно быть представлено артефактом типа json (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:json).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).OTHER
В хранилище артефактов описание Other API должно быть представлено артефактом типа zip (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:zip).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).Структура архива должна быть следующей:
<api-name>.zip // Архив с документацией на публичные API └── html/ ├── index.html // Корневой HTML файл прочей документации └── ... // Дополнительные файлы прочей документации если естьREST
В хранилище артефактов описание REST API должно быть представлено артефактом типа json (
groupId: groupId API,artifactId: artifactId API,version: версия API,type:json).В info.json можно дополнительно указать классификатор в
gav-classifier(необязательно).
Сборка документации#
API документация собирается одновременно с основным контентом при помощи workflow build-doc.
По завершении успешного выполнения workflow в отчете сборки будет доступна информация о сборке API документации:
Пример заполнения info.json#
Пример заполнения info.json:
{
"type": "JAVA",
"name": "Документация Java API",
"description": "Документ, в котором описаны интерфейсы и классы Java API",
"gav": {
"groupId": "group.id.example",
"artifactId": "artefact-id-example",
"version": "1.0.0"
},
"repo": {
"url": "ssh://git@mydomain:7998/code/api-demo.git",
"commit": "577af2f44b9",
"apidir": "/"
}
}
Схема info.json:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "info.schema.json",
"title": "Схема файла info.json",
"type": "object",
"properties": {
"type": {
"description": "Тип API",
"type": "string",
"enum": [
"GRAPH_QL",
"GRPC",
"JAVA",
"JSON_RPC",
"KAFKA",
"MQ",
"OTHER",
"REST"
]
},
"name": {
"description": "Название API",
"type": "string"
},
"description": {
"description": "Краткое описание",
"type": "string"
},
"gav": {
"description": "Уникальный составной идентификатор версии API",
"type": "object",
"properties": {
"groupId": {
"type": "string"
},
"artifactId": {
"type": "string"
},
"version": {
"type": "string"
},
"classifier": {
"type": "string"
}
},
"required": [
"groupId",
"artifactId",
"version"
]
},
"isOwn": {
"description": "API разработано СБТ (не является заимствованным)",
"type": "boolean",
"default": true
},
"repo": {
"description": "Репозиторий API",
"type": "object",
"properties": {
"url": {
"description": "SSH ссылка на репозиторий",
"type": "string"
},
"commit": {
"description": "Коммит",
"type": "string"
},
"apidir": {
"description": "Путь к API файлам",
"type": "string"
}
},
"required": [
"url",
"commit",
"apidir"
]
}
},
"required": [
"type",
"name",
"description",
"gav"
]
}