Swagger文档使用—knife4j风格

一、引入pom依赖

<!--springfox-Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <!--Swagger-UI 默认-->
        <!--访问路径：http://localhost:9091/doc.html-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
        <!--不加一下两个依赖，可能会报Illegal DefaultValue null for parameter type integer 异常-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
        </dependency>
        <!--对应的版本号 一般在聚合父工程中管理依赖-->
       <!-- <swagger2.default.version>2.9.2</swagger2.default.version>
        <springfox-swagger-ui.version>2.9.2</springfox-swagger-ui.version>
        <swagger-knife4j-version>2.0.4</swagger-knife4j-version>-->

二、新建SwaggerConfig配置类

package com.miswu.config;

/**
 * @author mis_wu
 * @date 2021/11/29 20:17
 */

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.miswu.utils.ResponseCode;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
@Configuration //applicationContext.xml
@EnableSwagger2//开启Swagger
@EnableKnife4j //开启knif4j
public class SwaggerConfig {
    //配置Swagger的bean实例
    @Bean
    public Docket docket(Environment environment) {
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        Arrays.stream(ResponseCode.values()).forEach(stateCodeEnum ->
        {
            responseMessageList.add(
                    /*new ResponseMessageBuilder()
                            .code(stateCodeEnum.getCode())
                            .message(stateCodeEnum.getMsg())
                            .responseModel(new ModelRef(stateCodeEnum.getMsg()))
                            .build());//这种形式swagger提示自定义返回msg找不到*/
                    new ResponseMessageBuilder()
                            .code(stateCodeEnum.getCode())
                            .message(stateCodeEnum.getMsg())
                            .build());
        });
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev");
        //获取项目环境：是生产环境还是发布环境
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                //添加全局状态码
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .groupName("cloud-admins-API")
                //是否启用swagger，如果为false则swagger不能再浏览器中访问
                .enable(flag)
                .select()//通过select()方法配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //指定扫描的api包
                .apis(RequestHandlerSelectors.basePackage("com.miswu.controller"))
                //any()：任何请求都扫描  ant()通过paths()方法配置扫描接口,PathSelectors配置如何扫描接口 "/sys/**"
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        //链式编程,固定
        return new ApiInfoBuilder()
                .title("管理员微服务中心接口文档")
                .description("cloud-admins RESTful APIS")
                .contact(new Contact("mis_wu","http://www.baidu.com","mis_wu1998@163.com"))
                .license("Apache 2.0 开源许可证")
                .version("1.0.0")
                .build();
    }
}

三、启动项目
访问：localhost:port/doc.html即可
四、常用API注解配置说明
1、@API() 作用在类上

//作用在模块API类上，对API模块进行说明
@Api(tags = "Admins-Controller-API")

2、@ApiOperation(“管理员登录登录”)

//作用在方法上
//作者说明,表明谁开发的这个接口
@ApiOperationSupport(author = "mis_xxx")
//方法说明
@ApiOperation("管理员登录登录")

3、@ApiParam(“登录信息”)

//作用在方法参数中,对参数说明
@ApiParam("登录信息")

4、@ApiModel(“用户实体类”)

//对实体类说明
@ApiModel("用户实体类")

5、@ApiModelProperty(“用户名”)

//对实体类属性说明
public class Users implements Serializable {
    @ApiModelProperty("用户名")
    private String loginId;
    @ApiModelProperty("密码")
    private String loginPwd;
    @ApiModelProperty("名称")
    private String nickName;
    @ApiModelProperty("电话")
    private String tel;
    @ApiModelProperty("头像")
    private String pic;
}