7.3.1 Swagger 文档生成工具

一.学习目标

  • 了解Swagger的作用和概念

  • 了解前后端分离

  • 在SpringBoot中集成Swagger

二.Swagger简介

  • 就是将代码生成API文档的

  • 号称世界上最流行的API框架

  • RestFul API文档在线自动生成工具 => API文档与API定义同步更新

  • 直接运行，可以在线测试API接口

  • 支持多种语言：（Java，PHP......）

1.官网：https://swagger.io

2.在项目中使用Swagger需要springfox

（1）springfox swagger2

（2）springfox swagger UI

三.SpringBoot集成Swagger

1.步骤：

  • 建立一个Springboot带Spring MVC的项目

  • 导入两个依赖swagger2和swaggerUI

  • 编写一个HelloController测试项目是否可以正常运行（略）

  • 编写config配置Swagger

  • 测试运行

2.新建SpringBoot的web项目

3.导入两个依赖swagger2和swaggerUI

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

4.编写config配置Swagger

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

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

}

5.测试运行

  • http://localhost:8080/swagger-ui.html

四.配置Swagger信息

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.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的Docker的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息
    private ApiInfo apiInfo() {

        //作者信息
        Contact contact = new Contact("wzh", "https://www.cnblogs.com/zhihaospace/", "464407764@qq.com");

        return new ApiInfo(
                "WZH的Swagger Api文档",
                "Api 文档",
                "1.0",
                "https://www.cnblogs.com/zhihaospace/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
    
}

五.配置Swagger扫描接口

  • enable：通过springboot配置文件来配置是否显示spring-ui.html页面，注意端口号

  • apis：配置需要扫描的路径

  • paths：配置过滤掉的路径

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 {

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


        //配置 在dev或test生产环境下可以显示swagger环境，release环境下看不到Swagger
        Profiles profiles = Profiles.of("dev","test");

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


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable 配置是否启用Swagger，为false则swagger-ui页面不能在浏览器中访问
                .enable(flag)
                .select()
                /*
                * RequestHandlerSelectors 配置要扫描接口的方式
                * 参数：
                *   basePackage("ustc.wzh.swagger") 指定要扫描的包
                *   withClassAnnotation(RestController.class) 扫描类上的注解，参数是一个类注解的反射对象
                *   withMethodAnnotation(GetMapping.class) 扫描方法上的注解，参数是一个方法注解的反射对象
                *   any() 扫描全部
                *   none() 不扫描
                */
                .apis(RequestHandlerSelectors.basePackage("ustc.wzh.swagger"))
                /*
                * paths 过滤路径（就是不去扫描的路径）
                * any() 全部过滤
                * none() 不过滤
                * regex(/[a-z]/) 过滤到正则表达式代表的路径
                * ant("xxx") 指定路径过滤
                */
                //.paths(PathSelectors.ant("/wzh/**"))
                .build()
                ;
    }

    //配置Swagger信息
    private ApiInfo apiInfo() {

        //作者信息
        Contact contact = new Contact("wzh", "https://www.cnblogs.com/zhihaospace/", "464407764@qq.com");

        return new ApiInfo(
                "WZH的Swagger Api文档",
                "Api 文档",
                "1.0",
                "https://www.cnblogs.com/zhihaospace/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

}

 六.配置API文档的分组

1.使用groupName方法设置即可

.groupName("WZH")

2.配置多个分组

  • 只需要多课Docket实例即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("AAA");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("BBB");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("CCC");
    }

七.实体类

  • 如果我们的接口中返回值存在的实体类，则这个实体类就会被扫描到Swagger中

  • 我们增加了@ApiModel和@ApiModelProperty注解就会在Swagger-ui中扫描到

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

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

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }
}

八.Controller中使用

  • 最重要的是测试功能，此时我们在控制器中故意写除零操作导致错误，Swagger会显示Response错误的详细详细内容

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;
import ustc.wzh.swagger.pojo.User;

@RestController
public class HelloController {

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

    @ApiOperation("获得user")
    @PostMapping(value = "/user")
    public User user(@ApiParam("用户名") String username,@ApiParam("密码") String password){
        int i = 5/0;
        return new User(username,password);
    }
}

 九.总结

  • Swagger可以给较难理解的属性或接口增加注释

  • 接口文档是实时更新的

  • 可以在线测试

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/zhihaospace/p/12424316.html