Apress::Documentation
Установка
gem 'apress-documentation'
Использвание
Описание любого компонена задается с помощью вызова метода build на главном модуле Apress::Documentation
и передаче ему блока. Например,
Apress::Documentation.build(:module_name, title: 'название модуля') do
document(:component, title: 'Название компонента') do
description 'test'
end
end
в самом блоке могут быть вызваны методы document, name, description, business_desc, consumers, publicity, tests, swagger_bind.
Описания методов
document
определеяет весь документ, является частью построения меню (на каждый документ создается ссылка), данный метод можно вызвать друг друге, например:
Apress::Documentation.build(:module_name, title: 'название модуля') do
document(:component, title: 'Название компонента') do
description 'test'
document(:nested_component, title: 'Вложенный документ') do
description 'test here'
publicity 'Закрытый'
end
end
end
также document
можно вызывать без блока, если нет неообходимости:
Apress::Documentation.build(:module_name, title: 'название модуля') do
document(:component, title: 'Простой компонент соящий упоминания')
end
title
- имя компонента.
description
- описание компонента.
business_desc
- бизнес-описание компонента, заполняется менеджером.
consumers
- перечесление модулей-потребителей.
tests
- есть ли тесты на компонент, когда были написаны, в рамках какой задачи.
publicity
- публичность компонента, возможность использования его в других местах, рекомендованные значения -
"Защищеный", "Публичный".
swagger_bind
реализует возможность дополнить swagger-ui.
разрешенные методы - business_desc, consumers, tests и publicity.
Пример использования:
Apress::Documentation.build(:module_name, title: 'название модуля') do
document(:http_api, title: 'HTTP API') do
# аргумент id HTML блока в который будет ставлена доп. инфа
swagger_bind('module_operationID_content') do
description 'Это апи нужно для того-то'
consumers 'Other module'
# тут обычное swagger описание
swagger_path('some/path/here') do
operation :get do
# важно чтобы operation_id и tags совпадали в аргументе swagger_bind
key :operationId, 'operationID'
key :tags, ['module']
...
end
end
end
# также аргумент HTML id можно опускать, если operationId и tags заданы
swagger_bind do
description 'Это апи нужно для того-то'
consumers 'Other module'
# тут обычное swagger описание
swagger_path('some/path/here') do
operation :get do
# Автоматически поддянет значения и создат HTML id - module_operationID_content
key :operationId, 'operationID'
key :tags, ['module']
...
end
end
end
end
end