在swagger注释中的param格式

在Swagger注释中，@param标签可用于指定API操作的参数信息，其中包括参数名称、参数类型、是否必填、默认值、描述等。@param标签的格式如下：

@param <参数名> <参数类型> [是否必填] [默认值] - <参数描述>

例如，下面是一个使用@param标签的例子：

// @param id path integer true "User ID" (required)

在这个例子中，@param标签指定了一个名为"id"的路径参数，类型为整数，必填，描述为"User ID"。如果参数不是必填的，那么就不需要写[是否必填]这个选项。如果参数有默认值，就可以通过[默认值]来指定。

相关问题

go swagger

### Go语言中使用Swagger进行API文档生成

在Go语言环境中，`Swaggo`是一个流行的工具集，用于自动生成基于Swagger的API文档。为了实现这一目标，开发者需先安装必要的依赖包[^2]。

#### 安装Swaggo及相关组件

通过执行以下命令可以完成所需库文件的下载：

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

这些命令分别获取了核心swagger生成器、gin框架下的swagger中间件以及静态资源管理模块。

#### 初始化项目结构并配置路由

假设已经创建了一个简单的HTTP服务器应用，在此之上添加对Swagger的支持涉及修改入口文件(main.go)，引入相应的初始化逻辑：

package main

import (
    "github.com/gin-gonic/gin"
    _ "your_project/docs" // 导入生成的docs包
)

// @title Gin Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

func main() {
    r := gin.Default()
    
    // 路由定义...
}

注意上述代码中的注释部分，它们遵循特定格式，用来描述整个API的信息，包括标题、版本号、联系方式等元数据。

#### 编写带有注解风格的Handler函数

为了让swag能够解析到具体的接口详情，需要按照其规定的模板给handler方法加上详细的说明性注释：

// @Summary Get user information by ID
// @Description Fetches the details of one single user based on their unique identifier (ID).
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} UserResponse
// @Failure 400 {string} string "Invalid input"
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    ...
}

这里的每一行都对应着不同的语义标签，比如路径参数(`@Param`)、返回状态码及其含义(`@Success`, `@Failure`)等等。

#### 执行Swagger文档生成功能

当所有的准备工作完成后，可以通过运行如下指令触发实际的文档构建过程：

swag init

这一步骤将会扫描源码目录下所有符合条件的方法签名，并据此产出对应的JSON/YAML格式的数据文件存放在指定位置，默认情况下会在项目的根路径新增一个名为`docs`的新子目录存放结果。

最后记得调整web服务启动脚本，使得访问者可以直接浏览在线版的交互式API文档页面。

go1.17如何在Goland项目中使用swagger

在 Go 1.17 中，你可以使用 embed 包将静态文件嵌入到可执行文件中，因此可以将 Swagger UI 嵌入到 Go Web 项目中，而不需要单独部署 Swagger UI。

以下是在 Goland 项目中使用 Swagger 的步骤：

1. 安装 Swagger 相关依赖：在项目中添加 `github.com/swaggo/swag` 和 `github.com/swaggo/gin-swagger` 两个依赖库，可以使用以下命令：

   go get -u github.com/swaggo/swag
   go get -u github.com/swaggo/gin-swagger
   go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. 在项目中添加 Swagger 注释：在需要生成 Swagger 文档的接口上添加注释，例如：

   // @Summary 获取用户信息
   // @Description 根据用户ID获取用户信息
   // @Tags 用户管理
   // @Produce json
   // @Param id path int true "用户ID"
   // @Success 200 {object} UserResponse
   // @Failure 400 {string} string "请求参数错误"
   // @Router /users/{id} [get]
   func GetUserByID(c *gin.Context) {
      // ...
   }

3. 生成 Swagger 文档：在项目根目录下执行以下命令，生成 Swagger 文档：

   swag init

该命令会在项目中生成一个 `docs` 目录，其中包含了 Swagger 文档的 JSON 文件和 HTML 文件。

4. 在项目中嵌入 Swagger UI：在项目中添加一个 `swagger` 目录，并将 Swagger UI 的静态文件拷贝到该目录中。可以从 Swagger 官网（https://swagger.io/tools/swagger-ui/）下载最新的 Swagger UI 版本。

   ├── main.go
   ├── go.mod
   ├── go.sum
   ├── docs
   │   ├── docs.go
   │   ├── swagger.json
   │   └── swagger.yaml
   └── swagger
       ├── index.html
       ├── swagger-ui-standalone-preset.js
       ├── swagger-ui-standalone-preset.js.map
       ├── swagger-ui.css
       ├── swagger-ui.css.map
       ├── swagger-ui.js
       ├── swagger-ui.js.map
       └── swagger-ui.min.js

5. 在项目中添加 Swagger UI 的路由：在项目中添加一个路由，将 Swagger UI 的 HTML 文件和静态文件提供给用户访问，例如：

   router.GET("/swagger/*any", gin.WrapH(http.FileServer(http.Dir("./swagger"))))

这样，用户可以通过访问 `/swagger/index.html` 来查看 Swagger 文档。

6. 启动项目并访问 Swagger UI：在 Goland 中启动项目，然后在浏览器中访问 `http://localhost:8080/swagger/index.html`，即可访问 Swagger UI 并查看文档。

需要注意的是，这种方式虽然可以将 Swagger UI 嵌入到可执行文件中，但是每次修改 Swagger UI 后都需要重新编译可执行文件，因此不建议在生产环境中使用。如果你需要在生产环境中使用 Swagger UI，建议单独部署一个 Swagger UI 服务。