在Spring Boot应用中，Swagger是一个强大的工具，用于生成RESTful API的文档，它使得开发者能够以交互式的方式测试和展示API。以下是如何在Spring Boot项目中整合Swagger的详细步骤及相关的注解说明。
为了引入Swagger，我们需要在项目的`pom.xml`文件中添加Springfox的依赖。具体如下：
```xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
```
这两个依赖分别提供了Swagger的核心库和用户界面，使我们能够生成和查看API文档。
接下来，我们需要创建一个配置类来初始化Swagger。这里以`SwaggerConfig`为例：
```java
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestUserApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("user")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.tedu.mycat.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("api文档的标题")
.description("api文档的描述")
.contact(new Contact("爱撒谎的男孩", "https://chenjiabing666.github.io", "18796327106@163.com"))
.version("1.0")
.build();
}
}
```
在这个配置类中，`Docket`对象定义了API的基本信息，如分组（groupName）、API信息（apiInfo）以及扫描的包路径（basePackage）。`apiInfo`方法则定义了API的元数据，包括标题、描述、联系人信息和版本号。
启动类上需要添加`@EnableSwagger2`注解，激活Swagger2的配置：
```java
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
完成上述配置后，通过访问`http://ip/projectName/swagger-ui.html`，你就可以看到生成的Swagger UI界面，用来展示和测试API。
Swagger注解主要有以下几个关键部分：
- `@Api`: 用于标记控制器类，表示该类是API的一部分。可以指定`value`（API的路径），`tags`（分类标签）和`description`（API的描述）等属性。
- `@ApiOperation`: 标记在控制器类的方法上，表示该方法是API的一个操作。可以指定`value`（操作的简短描述），`notes`（详细描述），`httpMethod`（HTTP方法，如GET、POST等），以及`response`（预期的响应类型）等属性。
- `@ApiParam`: 用于标记方法参数，表示该参数是API请求的一部分。可以指定`name`（参数名），`required`（是否必需），`value`（描述），以及`example`（示例值）等属性。
- `@ApiResponses`: 用于描述可能的API响应，包含一系列`ApiResponse`对象，每个`ApiResponse`对应一种响应码及其描述。
- `@ApiModel` 和 `@ApiModelProperty`: 分别用于标记实体类和实体类属性，提供关于模型和属性的描述信息。
通过这些注解，Swagger可以自动解析你的API，并生成详细的文档，方便其他开发者理解和使用你的API。在实际开发中，可以根据需求调整配置和注解，以满足不同API的文档需求。
