Swagger(Api接口管理)

Swagger(Api管理)

主要应用于前后端分离的项目，实时更新最新API，降低集成风险。
RestFul Api文档在线自动生成工具=》Api文档与Api定义同步更新
直接运行，可以在线测试API接口
支持多种语言

官网地址

#在项目中使用Swagger需要Springfox依赖;
& swagger2
& ui

SpringBoot集成Swagger

1、新建Springboot-web项目
2、在pom.xml中导入swagger依赖

<!--swagger2依赖 -->
        <!--https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <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>

3、编写一个可访问控制器接口备用
4、配置swagger（Config）

Docket：摘要对象，通过对象配置描述文件的信息。 apiInfo:设置描述文件中 info。参数类型 ApiInfo
select()：返回 ApiSelectorBuilder 对象，通过对象调用 build()可以 创建 Docket 对象

创建配置类测试运行

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {
}

1）尝试访问 http://localhost:8080/swagger-ui.html可见如下页面

2）配置Swagger

package com.autorestapi.swagger.config;

import io.swagger.annotations.Api;
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.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {

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

        //设置要启动swagger的环境
        Profiles profiles = Profiles.of("dev","test");
        //判断当前环境是否处在启动swagger的环境中 Environment系统环境变量
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                /**
                 *配置Swagger信息
                 */
                .apiInfo(apiInfo())
                .groupName("json-lu")//swagger分组，一个Docket实例就是一个分组，默认是default
                /**
                 * 配置是否启动swagger
                 *  如果为false,Swagger在浏览器中不能访问
                 */
                .enable(flag)//根据系统环境决定是否启动swagger
                .select()
                /**
                 * RequestHandlerSelectors,配置要扫描接口的方式
                 *      basePackage("包路径"):指定要扫描的包
                 *      any():扫描全部
                 *      none()：不扫描
                 *      withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                 *      withMethodAnnotation:扫描方法上的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.autorestapi.swagger.controller"))
                /**
                 *  过滤接口路径
                 *      PathSelectors,配置扫描接口中需要被过滤掉的路径
                 *      ant("访问路径"):过滤该访问路径的接口
                 *      any():过滤全部
                 *      none():不过滤
                 *      regex(正则):按照正则表达式过滤路径
                 */
                .paths(PathSelectors.ant("/user/**"))
                .build();
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("json-lu", "https://gitee.com/json-lu/", "freedStyle@163.com");
        return  new ApiInfo("My Swagger接口文档",//title
                "first Swagger",//描述
                "1.0",
                "https://gitee.com/json-lu/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

5、配置api文档的分组

如何配置多个分组:
创建多个Docket实例即可

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");//A分组
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");//B分组
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");//C分组
    }

---

常用注解

Model层：
@ApiModel("实体类注释")
@ApiModelProperty("属性名注释")

package com.autorestapi.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel("用户实体类")
@Data
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

Controller层：
@Api(tags="controller描述")
@ApiOperation("方法描述")
@ApiParam("参数描述")

package com.autorestapi.swagger.controller;

import com.autorestapi.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
@Api(tags = "Hello控制类")
@RestController
public class HelloController {

    /**
     * 一个项目一定有一个/error请求(任意请求路径)
     *  所以有两个请求路径 /error /hello
     * @return
     */
    @GetMapping(value = "/user/hello")
    @ApiOperation(value = "hello方法")
    public String hello(){
        return "hello";
    }

    /**
     * ApiOperation参数
     * value：方法描述
     * httpMethod:方法请求类型
     * notes:方法注释
     * tags:方法作用（标签）
     * @return
     */
    @GetMapping(value = "/user")
    @ApiOperation(value = "user方法",httpMethod = "GET",notes = "hello方法返回hello")
    public User getUser(){
        return new User();
    }

    @GetMapping(value = "/user/hello2")
    @ApiOperation("带参数hello方法")
    public String hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @PostMapping(value = "/user/hello3")
    @ApiOperation("带参数hello3方法")
    public String hello2(@ApiParam("用户名") @RequestBody String username){
        return "hello"+username;
    }
}

使用Swagger的优点：
1、我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
2、接口文档实时更新
3、可以在线测试