Существует ли автоматизированный способ документирования услуг Нэнси?

Есть ли способ автоматической генерации документации Swagger (или аналогичной) для службы Nancy?

Я нашел Nancy.Swagger, но нет никакой информации о том, как его использовать, и демонстрационное приложение, похоже, не демонстрирует генераторную документацию (если это так, не очевидно).

Любая помощь будет оценена по достоинству. Спасибо!

ОТВЕТЫ

Ответ 1

В моем текущем проекте я много искал эту проблему. Я использовал как nancy.swagger, так и nancy.swagger.attributes.

Я быстро отбросил Nancy.swagger, потому что для меня лично это не звучит правильно, что вам нужно создать чистый класс документации для каждого модуля nancy. Решение атрибутов было немного "чище" - по крайней мере, кодовая база и документация были в одном месте. Но очень быстро это стало недостижимым. Код модуля не читается из-за многих атрибутов. Ничего не генерируется автоматически: вам нужно указать путь, все параметры, даже метод http как атрибут. Это огромное дублирование усилий. Проблемы шли очень быстро, несколько примеров:

  • Я изменил POST на PUT в Nancy и забыл обновить атрибут [Method].
  • Я добавил параметр, но не атрибут для него.
  • Я изменил параметр из пути в запрос и не обновил атрибут.

Слишком легко забыть обновлять атрибуты (не говоря уже о решении модуля документации), что приводит к расхождениям между вашей документацией и фактической базой кода. Наша команда пользовательского интерфейса находится в другой стране, и у них возникли проблемы с использованием API-интерфейсов, поскольку документ просто не обновлялся.

Мое решение? Не смешивайте код и документацию. Создание документа из кода (например, Swashbuckle) нормально, но на самом деле писать документ в коде и пытаться дублировать код в документе НЕ. Это не лучше, чем писать в документе Word для ваших клиентов.

Если вам нужен документ Swagger, просто сделайте это способом Swagger. - Проведите некоторое время с помощью Swagger.Editor и действительно создайте свой API в  YAML. Он выглядит полностью текстовым и жестким, но как только вы привыкнете к нему, это  не. - Проведите некоторое время с Swagger.Codegen и адаптируйте его (он уже выполняет справедливую работу по созданию кода сервера Nancy и с несколькими  изменения в шаблонах усов - это то, что мне было нужно). - Автоматизируйте свой процесс: напишите пару партий, чтобы сгенерировать свои модули и модели из yaml и скопировать их в ваш репозиторий.

Преимущества? Довольно много:  -

  • Ваше определение YAML теперь является единственной истиной вашего контракта REST. Если где-то что-то дефферентно, это неправильно.
  • Код сервера Nancy автогенерируется
  • Клиентские кодовые базы автоматически генерируются (в нашем случае это android, ios и angular)

Поэтому всякий раз, когда я что-то меняю в REST-контракте, все кодовые базы восстанавливаются и добавляются к проектам в одной партии. Мне просто нужно сообщить командам, что что-то было обновлено. Им не нужно просматривать документы и искать их. Они просто восстанавливают свой код и, вероятно, видят некоторые ошибки компиляции в случае нарушения изменений.

Должен ли я использовать nancy.swagger(.nnotes)? Да, я использую его в другом проекте, который имеет только одну конечную точку с несколькими методами. Они не меняются часто. Это не стоит усилий, чтобы настроить все, у меня есть мой чванство документа быстро и работает. Но если ваш проект большой, API меняется, и у вас есть несколько кодовых оснований в зависимости от вашего API, мой совет - потратить некоторое время на реальную настройку swagger.

Ответ 2

Я цитирую ответ автора здесь из https://github.com/khellang/Nancy.Swagger/issues/59

Установка должна быть очень простой, просто вытащить пакет NuGet, добавить модули метаданных для описания ваших маршрутов и hit/api-docs. Это должно сделать вас JSON. Если вы хотите добавить swagger-ui, вы должны добавить это вручную прямо сейчас.