swagger

Swagger

• 号称世界上最流行的API框架
• RestFul风格的API展示可以实现API文档和API定义同步更新

SpringBoot整合Swagger

1. 导入相关依赖

<!-- 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>
<!--需要web的支持-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 写一个简单的Controller

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

3. 开启Swagger功能

@Configuration
@EnableSwagger2
public class SwaggerConfig {   
}

4. 访问swagger-ui.html

我们在ui的jar包中可以知道我们可以访问该页面

这是访问的页面

配置Swagger

Swagger中用来配置的bean是Docket

配置文档信息

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}
//配置swagger信息
public ApiInfo apiInfo(){
    return new ApiInfo(
            "swagger测试",//文档名称
            "初次测试swagger",//文档描述
            "1.0",//版本号
            "http://li-zhi.net.cn/",//作者个人博客
            new Contact("李智","http://li-zhi.net.cn/","1158778689@qq.com"),//作者联系方式
            "Apache 2.0",//开源协议
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
    );
}

配置模型

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

我是专门建了一个SwaggerModelConfig来放置所有的模型类

配置分组

因为项目一般是分组协同开发，每个组各自开发的接口，那接口文档应该各自分开，所以就有了分组的需要

分组只需要配置一个groupName(“groupName”)即可

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).groupName("group2");
}
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).groupName("group1");
}

配置扫描的接口

这里主要讲两种方式，第一种是按路径扫描，第二种是按包名扫描

按路径扫描

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).groupName("group1")
            .select()
            .paths(PathSelectors.ant("/user/**"))
			// 该配置下，该组会扫描所有的/user/下的所有的API
            .build();
}

按包名扫描

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).groupName("group2")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.lizhiswaggertest.controller"))
			//该配置下，该组会扫描所有此包下的API接口
            .build();
}

在类RequestHandlerSelectors中还有其他的扫描机制，可自行研究

根据环境控制是否能访问swagger

一般产品的开发都会有开发、测试、运维、上线等多套环境，根据不同的环境，控制是否可以访问swagger的ui界面

配置文件application.yml

---
server:
  port: 8081

spring:
  profiles: dev
---
server:
  port: 8082

spring:
  profiles: test
---
server:
  port: 8083

spring:
  profiles: pro
---

spring:
  profiles:
    active: dev

配置dev环境和test环境可以使用swagger

@Bean
public Docket docket1(Environment environment){
    Profiles devProfile = Profiles.of("dev","test");
    boolean dev = environment.acceptsProfiles(devProfile);
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).groupName("group1")
            .enable(dev);
}