| 注释 | 说明 | 示例 |
|---|---|---|
| title | 必填 应用程序的名称。 | // @title Swagger Example API |
| version | 必填 提供应用程序API的版本。 | // @version 1.0 |
| description | 应用程序的简短描述。 | // @description This is a sample server celler server. |
| tag.name | 标签的名称。 | // @tag.name This is the name of the tag |
| tag.description | 标签的描述。 | // @tag.description Cool Description |
| tag.docs.url | 标签的外部文档的URL。 | // @tag.docs.url https://example.com |
| tag.docs.description | 标签的外部文档说明。 | // @tag.docs.description Best example documentation |
| termsOfService | API的服务条款。 | // @termsOfService http://swagger.io/terms/ |
| contact.name | 公开的API的联系信息。 | // @contact.name API Support |
| contact.url | 联系信息的URL。 必须采用网址格式。 | // @contact.url http://www.swagger.io/support |
| contact.email | 联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。 | // @contact.email support@swagger.io |
| license.name | 必填 用于API的许可证名称。 | // @license.name Apache 2.0 |
| license.url | 用于API的许可证的URL。 必须采用网址格式。 | // @license.url http://www.apache.org/licenses/LICENSE-2.0.html |
| host | 运行API的主机（主机名或IP地址）。 | // @host localhost:8080 |
| BasePath | 运行API的基本路径。 | // @BasePath /api/v1 |
| accept | API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。 | // @accept json |
| produce | API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。 | // @produce json |
| query.collection.format | 请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。 | // @query.collection.format multi |
| schemes | 用空格分隔的请求的传输协议。 | // @schemes http https |
| x-name | 扩展的键必须以x-开头，并且只能使用json值 | // @x-example-key {“key”: “value”} |
使用Markdown描述
如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。
| 注释 | 说明 | 示例 |
|---|---|---|
| title | 必填 应用程序的名称。 | // @title Swagger Example API |
| version | 必填 提供应用程序API的版本。 | // @version 1.0 |
| description.markdown | 应用程序的简短描述。 从api.md文件中解析。 这是@description的替代用法。 |
// @description.markdown No value needed, this parses the description from api.md |
| tag.name | 标签的名称。 | // @tag.name This is the name of the tag |
| tag.description.markdown | 标签说明，这是tag.description的替代用法。 该描述将从名为tagname.md的文件中读取。 |
// @tag.description.markdown |
最后编辑: kuteng 文档更新时间: 2022-01-19 11:54 作者：kuteng
