是否有自动记录南希服务的方式？

Question

有没有办法为Nancy服务自动生成Swagger文档（或类似文件）？

我找到了Nancy.Swagger，但是没有关于如何使用它的信息，并且演示应用程序似乎没有展示生成文档（如果有的话，它并不明显）。

任何帮助将不胜感激。谢谢！

Answer 1

在我目前的项目中，我一直在研究这个问题。我使用了nancy.swagger和nancy.swagger.attributes。

我很快就放弃了Nancy.swagger，因为对我而言，你必须为每个nancy模块创建一个纯文档类是不对的。属性解决方案有点“干净” - 至少代码库和文档在一个地方。但很快就变得无法维持。由于许多属性，模块代码是不可读的。不会自动生成任何内容：您必须将路径，所有参数，甚至http方法作为属性。这是一个巨大的努力重复。问题来得非常快，举几个例子：

• 我在Nancy中将POST更改为PUT，忘记更新[Method]属性。
• 我添加了参数，但没有添加属性。
• 我将参数从路径更改为查询，但未更新属性。

忘记更新属性（更不用说文档模块解决方案）太容易了，这会导致文档与实际代码库之间出现差异。我们的UI团队在另一个国家，他们使用API​​时遇到了一些麻烦，因为文档并不是最新的。

我的解决方案？不要混合代码和文档。从代码生成文档（如Swashbuckle确实）是可以的，但实际上在代码中编写文档并试图在文档中公开代码是不是。它并不比为客户在Word文档中编写它更好。

如果您想要Swagger文档，只需以Swagger方式执行。 - 花些时间与Swagger.Editor合作，真正创作你的API    YAML。它看起来很全文，很难，但是一旦你习惯它，它就是    不。 - 花一些时间使用Swagger.Codegen并进行调整（它已经在生成Nancy服务器代码方面做得很好，并且有一些    调整胡子模板它就是我需要的东西）。 - 自动化您的流程：编写几个批次以从yaml生成模块和模型，并将它们复制到您的存储库。

<强>优势？不少：   -

• 您的YAML定义现在是您的REST合同的唯一真相。 如果某个地方有所不同，那就错了。
• 南希服务器代码是自动生成的
• 客户端代码库是自动生成的（在我们的例子中是android，ios和angular）

因此，每当我在REST合同中更改某些内容时，所有代码库都会重新生成并一次性添加到项目中。我只需告诉团队一些事情已经更新。他们不必浏览一些文档并搜索它。他们只是重新生成代码，如果发生变化，可能会看到一些编译错误。

我还在使用nancy.swagger（.annotations）吗？ 是的，我确实在另一个项目中使用它，它只有一个端点和几个方法。他们不经常改变。设置所有内容并不值得，我的swagger文档快速启动并运行。但是如果您的项目很大，API正在发生变化，并且您有多个代码库，具体取决于您的API，我的建议是花一些时间进行真正的招摇设置。

Answer 2

我在https://github.com/khellang/Nancy.Swagger/issues/59

引用作者答案

安装应该非常简单，只需下拉NuGet包，添加元数据模块来描述你的路线，然后点击/ api-docs。这应该会让你获得JSON。如果你想添加swagger-ui，你必须立即手动添加。

Answer 3

There is a nice article here: http://www.c-sharpcorner.com/article/generating-api-document-in-nancy-using-swagger/

Looks like you still have to add swagger-ui separately.

Answer 4

不。并非自动化。 https://github.com/yahehe/Nancy.Swagger需要大量手动创建的元数据。