Swagger

Swagger

背景

前后端分离式时代：

• 后端∶后端控制层，服务层，数据访问层【后端团队】
• 前端:前端控制层，视图层【前端团队】
  • 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来。
• 前端后如何交互? ————API
• 前后端相对独立，松耦合;
• 前后端甚至可以部署在不同的服务器上;

产生一个问题:

• 前后端集成联调，前端人员和后端人员无法做到"即使协商，尽早解决”，最终导致问题集中爆发;

解决方案：

• 首先指定schema[计划的提纲]，实时更新最新API，降低集成风险。
• 以前用Word计划文档
• 前后端分离
  • 前端测试后端接口 ：Postman
  • 后端提供接口，需要实时更新最新的消息及改动！

号称世界上最流行的Api框架

Restful API文档在线自动生成工具——>API文档与API定义同步更新

直接运行，在线测试接口

支持多种语言...

在项目中使用 需要springbox

• swagger2
• ui

springboot 集成swagger

1、新建一个springboot 项目

2、导入相关依赖

   <!--整合Swagger时使用-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <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>

3、写一个test工程

4、配置swagger——config

默认是swagger-ui.html

@Configuration //等价于@Component 让spring来加载该类配置
@EnableSwagger2 //开启Swagger2

//apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）

//RequestHandlerSelectors.basePackage()中填的是controller的目录
//apiInfo()方法中termsOfServiceUrl和contact可以用Contact的对象代替
//Swagger2已经不支持String类型的contact

createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置swagger的docket的bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("分组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dragon.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        //Contact contact = new Contact("阿龙", "https://i.cnblogs.com/", "1215374504@qq.com");
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("阿龙的SwaggerAPI文档")
                //.termsOfServiceUrl(" "https://i.cnblogs.com/"")
                //.contact("作者名")
                //.contact(contact)
                .version("1.0")
                .build();

    }
}

出题: 只希望Swagger在生产环境中使用，在发布的时候不使用

• 判断是不是生产环境 flag=false

• 注入enable（flag）

•     public Docket createRestApi(Environment environment) {
          //获取项目的环境
          Profiles profiles = Profiles.of("dev","pro");
          //判断是否处在自己设定的环境中
          boolean b = environment.acceptsProfiles(profiles);
  

@Profile("dev")

配置多个分组（实现 多个docket）

public class SwaggerConfig {
    @Bean
    public  Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public  Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public  Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类配置

只要接口中的返回值存在实体类，就会被扫描到swagger中

private属性 必须有get和set方法

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;

@GetMapping("/user")
public User user(){
    return new User();
}

@ApiOperation("post测试类")
@PostMapping("/test3")
public User post(@ApiParam("用户名") User user){
    int i = 5/0;
    return user;
}

总结

1、通过swagger给一些比较难理解的属性或者接口，增加注释信息

2、接口文档实时更新

3、可以在线测试