为Swagger编写api-doc

Question

我正在尝试使用Swagger，它说我应该从编写一个api开始，它描述了REST的确切api。问题是我不知道这意味着什么。这份文件是用通俗易懂的英语写的吗？或者是否有某种格式可以生成UI？

谢谢!

Answer 1

Swagger是描述REST的规范。规范的文档可以在这里找到- https://github.com/swagger-api/swagger-spec。

通常，有两种方法来记录API。如果已经有了包含代码的现有API，则可以使用任何现有库(https://github.com/swagger-api/swagger-spec#additional-libraries)集成到代码中，并在运行时生成文档。其中一些库还提供离线生成这样的文档。

如果您希望设计一个API，或者不想将另一个库集成到您的应用程序中，那么您可以在本地使用https://github.com/swagger-api/swagger-editor，也可以使用在线版本的http://editor.swagger.io。

一旦您有了文档，就可以使用Swagger来可视化和测试它。