Swagger–基础–02–集成Springboot
代码位置
https://gitee.com/DanShenGuiZu/learnDemo/tree/master/swagger_learn
1、代码结构
2、代码
User
package fei.zhou.business.business;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.ToString;
@Data
@ToString
@ApiModel(value = "用户实体", description = "用户实体信息")//推荐的另一种方式
//@Schema(title = "用户实体", description = "用户实体信息")
public class User {
@ApiModelProperty(value = "用户id", example = "1") //推荐的另一种方式
private String userId;
@Schema(title = "用户名", example = "张三")
private String userName;
}
UserController
package fei.zhou.business.business;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "人员信息接口")
@RestController
@RequestMapping("/userController")
public class UserController {
@ApiOperation(value = "新增用户", notes = "新增用户方法,注意请求方式是post,且这里没有权限校验")
@RequestMapping(value = "/add", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
//swagger :在方法位置定义响应参数
@ApiResponses({
@ApiResponse(responseCode = "401",description = "请进行身份验证"),
@ApiResponse(responseCode = "403",description = "拒绝执行"),
@ApiResponse(responseCode = "404",description = "资源未找到"),
@ApiResponse(responseCode = "500",description = "系统异常")
})
//swagger :在参数位置定义请求参数
public Integer add(@Parameter(name = "user", description = "用户实体参数", required = true) @RequestBody User user) {
return 1;
}
@RequestMapping(value = "/update", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
@ApiOperation(value = "修改", notes = "修改用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户id", defaultValue = "1", required = true, paramType = "query"),
@ApiImplicitParam(name = "userName", value = "用户名称", defaultValue = "1", required = true, paramType = "query")
})
//swagger :在方法位置定义请求参数
public Integer update(@RequestParam("userId") String userId, @RequestParam("userId") String userName) {
return 1;
}
@ApiOperation(value = "删除", notes = "删除用户")
@RequestMapping(value = "/delete", method = RequestMethod.DELETE)
//swagger :在参数位置定义请求参数
public Integer delete(@Parameter(name = "userId", description = "需要删除的用户id", required = true) @RequestParam("userId") String userId) {
return 1;
}
@ApiOperation(value = "查询", notes = "查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value = "/query", method = RequestMethod.GET)
public String query(@RequestParam("userId") String userId) {
return userId;
}
}
SwaggerConfig
package fei.zhou.business.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.Collections;
@Configuration
// 开启swagger
@EnableOpenApi
public class SwaggerConfig {
/**
* 创建API应用
* 一个Docket就是一个分组定义,表示哪几个接口暴露给Swagger页面
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) //指定使用 Swagger 3 版本的规范。
//组名称
.groupName("人员信息")
// // 标签
// .tags(new Tag("人员信息接口", "用户,角色,权限"))
//增加API相关信息
.apiInfo(apiInfo())
//配置接口的认证方式
.securitySchemes(Collections.singletonList(apiKey()))
.select()
// 指定扫描的包路径来定义指定要建立API的目录,到controller层即可。
.apis(RequestHandlerSelectors.basePackage("fei.zhou.business.business"))
// .apis(Predicates.and(Predicates.and(Predicates.or(
// // 添加扫描包路径,此处支持多个包扫描
// RequestHandlerSelectors.basePackage("com.example.demolearn.com.feizhou.business.business"),
// // 扫描@Api 注解的类(推荐方式 )
// RequestHandlerSelectors.withClassAnnotation(Api.class))))
.paths(PathSelectors.any())//扫描所有路径的接口
.build()
//是否启用这个分组,为false表示该定义暂不生效。
.enable(true);
}
//再定义一个Docket
@Bean
public Docket desertsApi2() {
return new Docket(DocumentationType.OAS_30)
.groupName("流程信息")
//API的基本信息
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("fei.zhou.business.business"))
.paths(PathSelectors.any())
.build()
.enable(true);
}
/**
* 创建该API的基本信息,包括标题、描述、版本等(这些基本信息会展现在文档页面中)
* 访问地址:http://ip:port/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("XX项目--Swagger3.0")
//Api文档描述
.description("这个openAPI的界面,前端可以通过这个去调试接口,后端人员写的内容要详细,保证前端能理解,减少沟通")
//配置联系方式(姓名,url,邮箱)
.contact(new Contact("周飞", "https://gitee.com/DanShenGuiZu/learnDemo/tree/master/swagger_learn", "920786312@qq.com"))
//服务器地址
.termsOfServiceUrl("https://gitee.com/DanShenGuiZu/learnDemo/tree/master/swagger_learn")
//版本信息
.version("1.0")
.build();
}
/**
*
* 用于配置接口的认证方式。
* 在这里,我们使用 API Key 的方式进行认证,
* @param
* @return springfox.documentation.service.SecurityScheme
* @author <a href="920786312@qq.com">周飞</a>
* @since 2023/8/9 15:13
*/
private SecurityScheme apiKey() {
//设置 认证头名称:Authorization
return new ApiKey("Authorization", "Bearer ", "header");
}
}
application.yml
server:
port: 8787
spring:
# 解决 Spring Boot 2.6.x 和 Swagger 3.0.0 版本兼容问题
mvc:
pathmatch:
matching-strategy: ant_path_matcher
pom.xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.6.10</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<!-- swagger 3.0 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
3、测试
http://localhost:8787/swagger-ui/index.html