Swagger

Swagger

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 （如：Java，PHP等）

1. SpringBoot集成Swagger

1. 创建springboot工程、引入web模块、编写一个hello world页面
2. 引入依赖jar包：
   • swagger2
   • ui

maven官网搜索：springfox swagger 找到swagger2和ui依赖引入：

<!--swagger 2-->
         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

整合knife4j总依赖：

 <!--swagger knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
        <!--springfox-swagger-ui -->
        <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
        <!--指定swagger-models版本，解决报错-->
        <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>

3. config中配置swagger2:

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

}

4. 运行测试;

http://localhost:8080/swagger-ui.html

2.配置swagger的api信息

//配置Swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//配置Swagger信息
    }
    //配置Swagger信息
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "钟情",           //标题
                "一往无前，远方",  //描述
                "v1.0",          //版本
                "https://blog.youkuaiyun.com/sentence5",   //组织链接
                new Contact("钟情", "https://blog.youkuaiyun.com/sentence5", "gz_qing@qq.com"),//作者信息
                "Apache 2.0",     //许可
                "http://www.apache.org/licenses/LICENSE-2.0",  //许可链接
                new ArrayList<VendorExtension>());  //扩展
    }

3.扫描接口

 //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//配置Swagger信息
        //是否启动swagger 如果是false则不能在浏览器中使用
                .enable(true)
                .select()
                //RequestHandlerSelectors. 配置要扫描的方式
                //basePackage():指定要扫描的包
                //any():扫描全部
                //none()：不扫描
                //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qing.swagger.controller"))
                //.paths() .过滤URL
                //any() 任何请求都扫描
                //none() 任何请求都不扫描
                //ant()	通过ant控制
                //regex() 通过正则表达式控制
                .paths(PathSelectors.ant("/qing/**")) //表示不扫描这里面的内容
                .build();
    }

4.配置swagger开关

1. 我只希望我在生产环境中使用，在正式环境不使用

• 判断是不是生产环境 flag=false
• 注入enable();

2. 新增两个配置文件：
   
   指定开发环境：#spring.profiles.active=dev

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger环境, 如果是dev环境就启动测试
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles判断是否处于自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                //配置要扫描的接口
                .apis(RequestHandlerSelectors.basePackage("com.qing.swagger.controller"))
                //.paths(PathSelectors.ant("/qing/**"))
                .build();
    }

    //配置Swagger信息
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "钟情",           //标题
                "一往无前，远方",  //描述
                "v1.0",          //版本
                "https://blog.youkuaiyun.com/sentence5",   //组织链接
                new Contact("钟情", "https://blog.youkuaiyun.com/sentence5", "gz_qing@qq.com"),//作者信息
                "Apache 2.0",     //许可
                "http://www.apache.org/licenses/LICENSE-2.0",  //许可链接
                new ArrayList<VendorExtension>());  //扩展
    }
}

5.配置api文档分组

1. 创建一个分组（一个dockert一个分组）：.groupName("钟情")
2. 创建多个分组

     //创建多个分组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

3. 注释

注释	含义
@Api(tags ="")	controller总接口注释
@ApiOperation("")	单个接口注释
@ApiParam("")	用户名参数注释
@ApiModel("")	实体类注释
@ApiModelProperty("")	实体参数注释

• 实体类注释：

@ApiModel("用户实体类") //类注释
public class User {
    @ApiModelProperty("用户名")  //字段注释
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

• 接口注释

@Api(tags ="用户相关接口")  //控制类总接口提示
@RestController
public class MyController {

    @GetMapping ("/hello")
    public String hello(){
        return "hello world";
    }

    @ApiOperation("返回对象接口") //单个接口提示
    @PostMapping("/user")
    public User user(){
        return new User();
    }
    @ApiOperation("返回用户名接口")
    @GetMapping("/hello2")
    public String user(@ApiParam("用户名参数") String username){
        return "hello"+username;
    }

}

swagger的增强UI -knife4j（转载https://blog.youkuaiyun.com/weixin_47083537/article/details/107484915）

knife4j简介

knife4j是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，提供了简洁、强大的接口文档体验。knife4j完全遵循了springfox-swagger中的使用方式，并在此基础上做了增强功能，如果你用过Swagger，你就可以无缝切换到knife4j。

使用方式：

1. 添加相关依赖：

        <!--指定swagger-models版本，解决报错-->
        <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>
<!--整合Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

2. 在config包下添加配置类

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
@EnableKnife4j   //开启knife4j的增强功能
public class Swagger2Config {
    
}

3. 运行我们的SpringBoot应用，访问API文档地址即可查看：http://localhost:8080/doc.html