Ответ 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.