SpringBoot项目集成Swagger2

前言

使用swagger2编写接口文档方便快捷，swagger2是为了方便前后端分离项目的交互，后端可以用来编写字段的描述，方便前端在对接口的了解每个字段的含义，不会把字段搞混，减轻前后端交互的压力，提高开发效率。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

注解说明

注解名	位置	描述
@Api	类上	标记该类为一个Swagger资源(API)，通常用在Controller上。可设置标签、描述等。
@ApiOperation	方法上	对一个API方法的描述，包括HTTP方法、请求路径、摘要、操作ID等。
@ApiParam	方法参数上	对API方法的参数进行描述，包括名称、是否必需、参数类型、默认值等。
@ApiModel	类上	用于对象作为请求体或响应体时，描述该对象的结构。
@ApiModelProperty	类的属性上	描述一个模型属性的意义，包括是否必需、默认值、示例值等。
@ApiResponse	方法上或@ApiResponses上	描述一个API响应的信息，如响应码、描述、响应体类型等。
@ApiResponses	方法上	包含多个@ApiResponse注解，用于表示一个API可能返回的所有响应。
@ApiIgnore	类、方法或参数上	忽略该元素，使其不生成到Swagger文档中。
@ApiImplicitParam	方法上	用于描述非请求体中的参数，如路径参数、查询参数、头信息等。
@ApiImplicitParams	方法上	包含多个@ApiImplicitParam注解，用于表示一个方法可能包含的所有隐式参数。
@Authorization	类或方法上	已废弃，建议使用全局安全配置或@SecurityRequirement。
@SecurityDefinitions	配置类上	定义安全方案，如OAuth2、API密钥等，现已被@SecurityScheme替代。
@SecurityScheme	配置类上	定义安全方案，如OAuth2、Basic Auth等，用于全局安全配置。
@SecurityRequirement	类或方法上	引用在@SecurityDefinitions或@SecurityScheme中定义的安全方案，表示API需要的安全认证。
@Deprecated	用于修饰方法或类，表示它们已经过时。	无属性，通常用于提醒开发者API已经不再推荐使用
@SecurityDefinition	定义API的认证方式。	name: 认证方式名称 type: 认证类型（如apiKey、basicAuth、oauth2） description: 描述信息 in: 认证信息的发送位置（如header、query）
@ApiParamImplicit	用于修饰方法的参数，	表示方法的隐式参数。可以设置 name、value 等属性来描述参数。
@ApiParamImplicitHeader	用于修饰方法的参数，	表示方法的隐式头参数。可以设置 name、value 等属性来描述头参数。
@ApiParamImplicitQuery	用于修饰方法的参数，	表示方法的隐式查询参数。可以设置 name、value 等属性来描述查询参数。
@ApiParamImplicitCookie	用于修饰方法的参数，	表示方法的隐式 cookie 参数。可以设置 name、value 等属性来描述 cookie 参数。
@ApiModelImplicit	用于修饰方法的参数，	表示方法的隐式模型。可以设置 name、value 等属性来描述模型。
@ApiModelImplicitProperty	用于修饰方法的参数，	表示方法的隐式属性。可以设置 name、value 等属性来描述属性。

常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
以下是一些在Swagger（特别是Swagger 2.x，通过Springfox实现）中常用的注解。

注解名称	属性名称	备注	简要说明
@Api	value	url的路径值	用来定义整个Controller的基路径，但不直接映射到具体的URL上，而是作为Swagger UI中该Controller下所有API的根路径。
	tags	如果设置这个值，value的值会被覆盖	用于为Controller分类，Swagger UI会根据这个值来分组显示API。
	description	对api资源的描述	提供对整个Controller或API接口的详细描述。
	basePath	基本路径	在Swagger 2.x中，这个属性通常不是通过@Api注解来设置的，而是全局配置或通过其他方式指定。
	position	如果配置多个Api，想改变显示的顺序位置	用来控制Swagger UI中API列表的显示顺序，但注意，并非所有版本的Swagger UI都支持此功能。
@ApiOperation	value	操作的简要说明	用来描述一个API接口的作用。
	notes	对操作的详细说明	提供对API接口的详细描述，比value更详细。
	tags	可以重新覆盖类级别的tags	在方法级别重新指定或覆盖Controller级别的tags。
	response	默认响应类	指定API接口的默认响应类型。
	responseContainer	响应的包装类型	指定响应数据的包装类型，如List或Set。
	produces	如, “application/json, application/xml”	指定API接口支持的响应媒体类型。
	consumes	如, “application/json, application/xml”	指定API接口支持的请求媒体类型。
	protocols	协议类型，如: http, https, ws, wss	指定API接口支持的协议类型，但通常不常用。
	authorizations	高级特性认证时配置	指定API接口所需的安全认证方式。
	hidden	配置为true，将在文档中隐藏	将API接口从Swagger UI中隐藏。
@ApiParam	name	参数名	指定请求参数的名称。
	value	参数的简要说明	对请求参数的简要描述。
	required	是否必须传值	指定请求参数是否必须。
	defaultValue	参数的默认值	为请求参数提供默认值。
@ApiModel	value	对象的名称	用来描述一个Java类的名称，该类将被用作API接口的请求或响应体。
	description	对api模型的描述	对API模型（即Java类）的详细描述。
@ApiModelProperty	value	字段说明	对模型属性的简要描述。
	example	示例值	为模型属性提供一个示例值。
	hidden	是否隐藏	将模型属性从Swagger UI中隐藏。
	required	是否必须	指定模型属性是否必须。
@ApiImplicitParams	-	-	用于包含多个@ApiImplicitParam注解，以定义多个请求参数。
@ApiImplicitParam	name	参数名	指定请求参数的名称。
	value	参数的简要说明	对请求参数的简短描述。
	dataType	参数的数据类型	指定请求参数的数据类型（如"integer", "string"等）。
	paramType	参数类型	指定请求参数的来源（如"query", "path", "header", "body", "form"）。
	required	是否必须	指定请求参数是否必须提供。
	defaultValue	参数的默认值	为请求参数提供一个默认值。
	example	示例值	为请求参数提供一个具体的示例值。

• @ApiModel：用对象来接收参数，放在类上面
• @ApiModelProperty：用对象接收参数时，描述对象的一个字段，放在字段上面

@Data
@ApiModel(value="User对象", description="用户类")
public class User {
   
   

    @ApiModelProperty(value = "用户ID")
    private Integer id;

    @ApiModelProperty(value = "名称")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;
    
}

最终界面展示