Swagger--基础--2.1--集成Springboot2--swagger3

Swagger–基础–2.1–集成Springboot2–swagger3

---

代码位置

https://gitee.com/DanShenGuiZu/learnDemo/tree/master/swagger_learn/swagger2

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