Spring Boot 整合 Swagger

Spring Boot 整合 Swagger

Swagger

简介

• 用于前后端联调，后端自动生成接口文档，前后端可以部署在不同的服务器上，所以为了保证实时性，后端接口一设计就会实时的生成接口文档，前后端相互独立，通过API交互。
• RestFul Api 文档在线自动生成工具=>Api文档与Api定义同步更新。
• 直接运行，可以在线测试api
• 支持多种语言
• 官网：https://swagger.io/
• 访问：http://localhost:8080/swagger-ui.html

使用

• 依赖导入swagger2和swagger-ui

<!--swagger2-->
<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>

• swaggerConfig

package com.qiumin.springbootshiro.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
public class swaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
                .build();
    }


    private ApiInfo getApiInfo(){
        Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
        return new ApiInfo("邱敏的SwaggerAPI文档",
                "自律也是一门学问",
                "v1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

• 配置一个Docket和一个ApiInfo方法用于Docket。
• 为了解决由于springboot版本过高的问题，需在springboot的配置文件加上spring.mvc.pathmatch.matching-strategy=ant_path_matcher

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

21.1 根据环境判断是否开启swagger

package com.qiumin.springbootshiro.config;

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 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 {

    @Bean
    public Docket docket(Environment environment){
        //根据环境判断是否开启swagger
        Profiles profiles=Profiles.of("dev","test"); //dev test环境下开启
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .enable(flag)  //dev test环境下开启
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qiumin.springbootshiro.controller"))
                .build();
    }


    private ApiInfo getApiInfo(){
        Contact contact = new Contact("邱敏", "https://blog.kuangstudy.com/", "2784618689@qq.com");
        return new ApiInfo("邱敏的SwaggerAPI文档",
                "自律也是一门学问",
                "v1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

21.2 分组及接口注释

分组

• 每一个Docket就是一个组，下面就表示为有三个组，分组可以协作开发，每个人将自己的接口放在自己的组中。

@Bean
public Docket docket2(){  //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin1").apiInfo(getApiInfo());
}

@Bean
public Docket docket3(){  //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin2").apiInfo(getApiInfo());
}

@Bean
public Docket docket4(){ //一组
    return new Docket(DocumentationType.SWAGGER_2).groupName("qiumin3").apiInfo(getApiInfo());
}

接口注释：我们可以用注解对接口进行解释说明

• 实体类的注解即实体类中字段的解释@ApiModel，@ApiModelProperty，标上了这两个注解在那个swagger页面就会有对应的解释说明

@Data
@AllArgsConstructor
@NoArgsConstructor
//注释
@ApiModel("用户类")
public class userPojo {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("用户权限")
    private String perms;
}

• 配置一个访问接口

@RequestMapping("/user")
@ResponseBody
public userPojo getuserPojo(){
    return new userPojo();
}

• 接口注释 @ApiOperation(“自定义”)

@ApiOperation("登出请求")
@RequestMapping("/loginOut")
private String loginOut(){
    Subject subject = SecurityUtils.getSubject();
    subject.logout();
    return "index";
}

• 参数注释 @ApiParam

@RequestMapping("/loginOut")
private String loginOut(@ApiParam("用户名") String username){
    Subject subject = SecurityUtils.getSubject();
    subject.logout();
    return "index";
}

21.3 swagger总结

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

2. 接口文档实时更新

3. 在swagger页面可以进行测试，通过接口向后端请求数据

4. 可在线测试 【try it】

5. 注意点：项目正式发布的时候应将swagger关闭，防止将接口暴露给外界，造成信息安全隐患，而且可以节省运行内存。

   return “index”;
   }

### 21.3 swagger总结

1. 可以通过swagger给一些比较难理解的属性或者接口，增加注释信息
2. 接口文档实时更新
3. 在swagger页面可以进行测试，通过接口向后端请求数据
4. 可在线测试 【try it】
5. **==注意点：项目正式发布的时候应将swagger关闭，防止将接口暴露给外界，造成信息安全隐患，而且可以节省运行内存。==**



**qiumin**