Swagger

1. 简介

• 号称世界上最流行的API框架
• RestFul API 文档在线自动生成工具 => API文档与API定义同步更新
• 直接运行,可以在线测试API接口
• 支持多种语言
• 在项目中使用Swagger需要SpringFox
  • Swagger2
  • ui

2. SpringBoot集成Swagger

1. 导入依赖

Swagger3.0直接导入Springfox Boot Starter就可以了

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.X版本需要导入Swagger2.0和UI

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

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

我们这里还是使用2.X版本

2. 配置Swagger

package com.wang.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

注意

• 只要在Swagger配置类上加上@EnableSwagger2注解,就可以使用Swagger2了
• Swagger的地址为http://localhost:8080/swagger-ui.html

3. Swagger配置

1. 配置Swagger信息

Swagger的Bean实例 ==> Docket

package com.wang.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

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

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("wang","https://www.cnblogs.com/wang-sky/","715180879@qq.com");

        return new ApiInfo(
                "我的Swagger接口文档","这是一个Swagger接口文档","V 1.0",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<VendorExtension>());
    }


}

这里修改的是Swagger页面的一些信息,结果如下

注意

• Docket不要忘了注册Bean并返回一个new Docket
• 返回的Docket要传入一个参数指定产生的文档的类型,我们这里使用 DocumentationType.SWAGGER_2

2. Swagger配置扫描接口

Docket.select()

@Bean
public Docket docket() {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描全部
    none            都不扫描
    withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象,比如 withClassAnnotation(RestController.class)
    withMethodAnnotation    扫描方法上的注解
     */
    //paths 过滤的路径,需要传入PathSelectors.xxx 选择过滤的方式
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build();
}

注意

• apis 扫描,要传入RequestHandlerSelectors.xxx 指定扫描的方式
  • basePackage 指定要扫描的包
  • any 扫描全部
  • none 都不扫描
  • withClassAnnotation 扫描类上的注解,比如 withClassAnnotation(RestController.class)
  • withMethodAnnotation 扫描方法上的注解
• paths 过滤的路径,需要传入PathSelectors.xxx 选择过滤的方式
• 最后要.build(),建造者模式,同时由于这是链式编程,一定要写!
• select().XXX.XXX...bulid()是一套,中间可以写的方法是确定的,不能乱写

3. 配置Swagger是否启动

只在生产环境下使用Swagger,而在发布的时候不使用的方法

分别建立不同环境的yml

在application中选择启动的环境,这里选择生产环境

spring:
  profiles:
    active: dev

配置Swagger

//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描全部
    none            都不扫描
    withClassAnnotation 扫描类上的注解,需要传入PathSelectors.xxx 选择过滤的方式

    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");

    //通过environment.acceptsProfiles,判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build()
            .enable(flag);
}

注意

• .enable
• 只能在select().XXX.XXX....bulid() 外面写
• 默认为true,如果为False,则Swagger不能在浏览器中访问
• 要用 Profiles profiles = Profiles.of("dev"); 指定激活的环境的名字
• 获得当前的生产环境(application指定的环境),要给Docket传入一个Environment对象,其中保存了当前环境的名字
• environment.acceptsProfiles(profiles); 利用此方法获得是否在给定环境的布尔值

4. 配置API文档的分组

.groupName("我的API")

配置多个分组,只需要配置多个Docket即可

4. 实体类配置

1. 实体类的注解

package com.wang.pojo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
//@Api("注释")
@ApiModel("用户实体类")
public class User {

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

@ApiModel或者@Api在类上

@ApiModelProperty在属性上

属性为私有,要写getter才能取到属性名

结果显示在Model上

2. 接口类的注解

package com.wang.controller;

import com.wang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello() {
        return "Hello!";
    }

    //只要我们的接口中,返回值中存在实体类,他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    //Operation接口
    //Get请求中,如果添加了字段的注释@ApiParam,Swagger无法测试
    @ApiOperation("Hello2接口")
    @GetMapping("/hello2")
    public String hello2(String username) {
        return "hello " + username;
    }

    //Operation接口
    @ApiOperation("Hello3接口")
    @PostMapping("/hello3")
    public User hello3(@ApiParam("用户") User user) {
        return user;
    }
}

注意

• 只要我们的接口中,返回值中存在实体类或者字符串,他就会被扫描到Swagger中
• @ApiOperation 方法的注释
• @ApiParm 参数的注释
• Get请求中,Swagger无法测试

5. 总结

• 我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
• 接口文档实时更新
• 可以在线测试
• 注意,在正式发布的时候,关闭Swagger(出于安全考虑,而且节省运行内存)

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!