如果没有关于我们API的有意义的文档以及对端点进行测试的能力，用户甚至都不会费心尝试使用它。解决方案是编写文档。但是，编写它可能要花费很多时间，否则可能会为我们的应用程序开发更多很棒的功能……那么，我们该怎么办？-我们生成了Swagger文档！

swagger库

让我们从创建Swagger文档所需的库开始。在swag文档中，有指向受支持框架的库的链接，其中包括net/http许多人喜欢使用的最简单的选项以及GIN，我将使用并在此处显示。即使您使用的是不同的Web框架，注释也将是相同的，因此您仍然可以在此处学习一些知识。

还值得一提的是，还有替代的Golang Swagger库-go-swagger似乎更受欢迎，而且功能也更强大。但是，我个人更喜欢swaggo/swag它的简单性。如果您需要对生成的内容进行更多控制，则可能需要切换到go-swagger。

字串

现在，对于批注/注释/文档字符串或任何您想调用的名称。实际上，在用于生成Swagger文档的特定API函数之前，实际上只是一堆注释。

在描述各个API端点之前，我们需要首先为整个项目编写一般描述。这部分注释位于函数的main紧前面的包中main：

在上面，您可以看到General API Info的示例，其中包括名称，版本，许可证，基本URL等内容。您可以包含更多字段，并在此处列出了一些示例。

除了注释之外，我们还需要导入必要的库，包括空白导入docs我们必须生成的包（稍后将对此进行更多介绍）。我们需要做的另一件事是将Swagger UI实际安装在某个端点，这里我们使用"/swagger/*any。

现在是重要部分-API函数的注释。这些注释在连接main到每个服务于某个端点的每个函数之前，因此，当我们为端点提供服务时v1.GET("/users/:id", apis.GetUser)，我们需要这样标注它：

其中大多数都是不言自明的，实际上这是应该包含的最少批注。我要强调的一件事是models.User成功返回-这是一种驻留在models包中的数据库表模型。通过这样引用它，我们使其在模型部分的Swagger UI中显示：

生成！

最后，是时候生成文档了！您只需要一个命令-?swag init，该命令需要从目录中运行main，因此对于我创建的蓝图存储库而言，它将是.../cmd/blueprint/。此命令将创建名为的程序包docs，其中包含我们文档的JSON和YAML版本。

即使生成了此程序包，我还是希望将其存储在GitHub中，因为它已导入到main程序包中，因此运行应用程序是必需的。如果要避免将生成的代码推送到GitHub，则可以编写一个Makefile目标，该目标将在构建和运行应用程序之前即时重新生成Swagger文档。但是，如果您决定将其推送到GitHub，则可能需要运行文档，go fmt因为它不一定要“按原样”格式化。

认证方式

此时，我们可以只运行应用程序，查看新的Swagger UI，然后将其命名为“一天”。但是缺少的一件事是对API的身份验证。如果您不对Swagger UI进行身份验证，那么任何人都可以访问他们想要的任何端点，这可能是非常不希望的，例如，如果您的数据可能被用户损坏。更糟糕的是，您可能会将数据库中的敏感信息公开到整个Internet。我认为这些足以为我们的API以及Swagger UI设置一些简单的身份验证，那么我们该怎么做呢？

首先，我们需要实际实现身份验证。这是GIN的情况，我们创建了一个非常简单的身份验证中间件，将其附加到路由器组：

通过将中间件附加到特定的组，我们可以控制什么是未认证的，什么是未认证的，这很重要，因为例如，我们不想对Swagger UI本身进行认证。

注意：为了使示例易读易懂，我省略了一些代码。有关完整代码，请参见此处的*rest-api*存储库中的分支。

我们需要在main模块中更改的另一件事是注释-更具体地说，我们需要添加securityDefinitions注释：

正如您已经猜到的那样，此注释通过Swagger UI的Authorization标头添加了API密钥身份验证。除了API密钥身份验证之外，您还可以选择使用用户名和密码或某些版本的OAuth2（）使用基本身份验证（），所有选项均在此处的文档中显示。我个人喜欢使用API??密钥，因为它很简单，也是我认为最方便的选择。securitydefinitions.basic``securitydefinitions.oauth2

为了使Swagger能够识别出某些端点已通过身份验证，我们还需要向该API函数添加安全注释：

这是最后一步，现在（在重新生成Swagger文档之后），我们终于可以运行我们的应用程序了：

现在，我们可以在http//localhost:1234/swagger/index.html上打开Swagger UI并测试我们的文档！

有疑问加站长微信联系（非本文作者）