Swagger 介绍
Swagger 是一个开源的框架,用于设计、构建、文档化和使用 RESTful 风格的 Web 服务。Spring Boot 是一个用于构建独立的、基于生产级别的 Spring 应用程序的框架。它可以集成 Swagger 来简化 RESTful API 的开发和文档生成。
通过集成 Swagger,你可以在 Spring Boot 应用程序中自动生成 API 文档,这些文档描述了你的 API 的各种端点、请求参数、响应等详细信息。Swagger 还提供了一个交互式 UI,让开发人员可以方便地浏览和测试 API。
所需的依赖
<!-- lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.28</version>
</dependency>
<!--引入spring web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入swagger3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<!--Knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
SwaggerConfig配置文件
package com.test.testdemo.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
/**
* @Author Chenry.r
* @Date 10/9/2023 上午1:11
* @Version 1.0
* @Description <p>备注:Swagger配置</p>
*/
@Configuration
@EnableOpenApi
@EnableKnife4j
public class SwaggerConfig {
// swagger3的配置文件
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.basePackage("com.test.testdemo.controller"))
.paths(PathSelectors.any())
.build()
//.globalRequestParameters(getGlobalRequestParameters())
.globalResponses(HttpMethod.GET, getGlobalResponseMessage())
.globalResponses(HttpMethod.POST, getGlobalResponseMessage())
.globalResponses(HttpMethod.DELETE, getGlobalResponseMessage())
.globalResponses(HttpMethod.PUT, getGlobalResponseMessage());
}
/**
* 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
*/
private ApiInfo apiInfo() {
// 获取工程名称
String projectName = System.getProperty("user.dir");
return new ApiInfoBuilder()
.title(projectName.substring(projectName.lastIndexOf("\\") + 1) + " API接口文档")
.contact(new Contact("Chenry.r", "http://127.0.0.1:8080/doc.html", "3347654141@qq.com"))
.version("1.0")
.description("API文档")
.build();
}
/**
* 生成通用响应信息
*
* @return
*/
private List<springfox.documentation.service.Response> getGlobalResponseMessage() {
List<Response> responseList = new ArrayList<>();
responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
return responseList;
}
}
实体类注解使用
package com.test.testdemo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.ToString;
/**
* @Author Chenry.r
* @Date 10/9/2023 上午1:24
* @Version 1.0
* @Description <p>备注:用户实体类</p>
*/
@Data
@ToString
@ApiModel(value = "用户实体类", description = "用户信息描述类")
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
}
Controller 接口注解使用
package com.test.testdemo.controller;
import com.test.testdemo.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
/**
* @Author Chenry.r
* @Date 10/9/2023 上午1:18
* @Version 1.0
* @Description <p>备注:UserController</p>
*/
@RestController
@Api(tags = "用户数据接口") // @Api 注解标注在类上用来描述整个 Controller 信息。
public class UserController {
// @ApiOperation 注解标注在方法上,用来描述一个方法的基本信息。
@ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")
@PutMapping("/user")
public String updateUser(@RequestBody User user) {
return user.toString();
}
/**
* @ApiImplicitParam 注解标注在方法上,用来描述方法的参数。其中 paramType 是指方法参数的类型,有如下可选值:
* 1、path:参数获取方式为 @PathVariable 2、query:参数获取方式为 @RequestParam 3、header:参数获取方式为 @RequestHeader
* @param id
* @return
*/
@ApiOperation(value = "查询用户", notes = "根据 id 查询用户")
@ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id) {
return "查找的用户id是:" + id;
}
/**
* 如果有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中
* @param username
* @param password
* @return
*/
@ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "username",
value = "用户名", required = true, defaultValue = "test"),
@ApiImplicitParam(paramType = "query", name = "password",
value = "密码", required = true, defaultValue = "123")
})
@PostMapping("/user")
public String addUser(@RequestParam String username, @RequestParam String password) {
return "新增用户:" + username + " " + password;
}
/**
* @ApiResponse 是对响应结果的描述。code 表示响应码,message 为相应的描述信息。如果有多个 @ApiResponse,则放在一个 @ApiResponses 中
* @param id
* @return
*/
@ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
@ApiResponses({
@ApiResponse(code = 200, message = "删除成功!"),
@ApiResponse(code = 500, message = "删除失败!")
})
@DeleteMapping("/user/{id}")
public Integer deleteUserById(@PathVariable Integer id) {
return id;
}
/**
* @ApiIgnore 注解表示不对某个接口生成文档。
* @return
*/
@ApiIgnore
@GetMapping("/user/test")
public String test() {
return "这是一个测试接口,不需要在api文档中显示。";
}
}
错误记录
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
在 application.yml 或applicaiton.properties 中添加如下配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
生产环境关闭Swagger
springfox.documentation.enabled=false: 这表示是否启用Springfox的文档生成功能。如果设为false,则不会自动生成API文档。
springfox.documentation.auto-startup=false: 这表示是否在Spring应用启动时自动启动Swagger服务。如果设为false,则Swagger服务不会自动启动,你需要手动启动。
springfox.documentation.swagger.v2.enabled=false: 这表示是否启用Swagger 2的文档生成功能。如果设为false,则不会生成Swagger 2格式的API文档。
访问测试
1、swagger原生ui访问地址:http://localhost:8080/swagger-ui/index.html
2、knife4j文档的访问地址:http://localhost:8080/doc.html