Spring Boot第六篇-整合Swagger

1.配置要求：JDK1.8+IDEA+SpringBoot+Swagger

Spring Boot版本要求在2.59以下，swagger2的依赖要在2.9.2，太高看不了源码，太低会报同下的错误

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

2.添加依赖

<!-- 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>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>

3.新建一个SpringBootWeb项目

4.编写config类

package com.example.demo.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.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 {
    //测试路径http://localhost:8080/swagger-ui.html
  /*  @Bean
     public Docket docket(){
         return new Docket ( DocumentationType.SWAGGER_2 ).apiInfo ( apiInfo () );
     }*/

  /*  //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact ("wdfxfff", "https://blog.youkuaiyun.com/wdfxfff?type=blog", "2864483641@qq.com");
        return new ApiInfo(
                "博客优快云", // 标题
                "座右铭：滴水一定会石穿", // 描述
                "v1.0", // 版本
                "https://blog.youkuaiyun.com/wdfxfff?type=blog",
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<> ()// 扩展
        );
    }*/
}

5.用测试路径测试  http://localhost:8080/swagger-ui.html

    出现界面即配置成功

6.添加文档信息

package com.example.demo.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.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 {
    //测试路径http://localhost:8080/swagger-ui.html
    @Bean
     public Docket docket(){
         return new Docket ( DocumentationType.SWAGGER_2 ).apiInfo ( apiInfo () );
     }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact ("wdfxfff", "https://blog.youkuaiyun.com/wdfxfff?type=blog", "2864483641@qq.com");
        return new ApiInfo(
                "博客优快云", // 标题
                "座右铭：滴水一定会石穿", // 描述
                "v1.0", // 版本
                "https://blog.youkuaiyun.com/wdfxfff?type=blog",
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<> ()// 扩展
        );
    }
}

我们首先打开源码看一下代码配置如何得来的

6.1 打开EnableSwagger2类

我们可以看到该文档需要@Configuration表示这是一个配置类

Swagger实例Bean是Docket，要通过配置Docket实例来配置Swaggger参数

6.2继续打开Docket 的源码

该源码只有一个构造器，我们再打开DocumentationType源码看一个常量和构造器

 

 该构造器需要 name，version，mediaType为参数调用构造器，上述常量即是Swagger2需要使用的。

6.3我们在再回看下Docket 的源码

该方法需要ApiInfo作为参数，我们再去看下 ApiInfo的源码

该源码只有一个构造器， 两个关键常量

第一个常量中用到了Contact，我们再去看下它的源码

只有一个构造器。。。

配置之后打开测试路径，结果

7.配置扫描的接口

 @Bean
     public Docket docket(){
         return new Docket ( DocumentationType.SWAGGER_2 )
                 .apiInfo ( apiInfo () )
                 .select ()
                 .apis ( RequestHandlerSelectors.basePackage ( "com.example.demo.controller" ) )
                 .paths ( PathSelectors.ant ( "/example/**" ) ).build ();
     }

RequestHandlerSelectors配置要扫描的接口方式

看下它的源码

 需要一个包来作为参数，basePackage指定需要扫描的包

 withMethodAnnotation扫描方法上的注解，参数是一个注解

 withClassAnnotation扫描类上的注解，参数是一个注解

打开Docket源码中找到select（）方法，可以看到该方法需要建立api selector

 我们在打开api selector看下是什么鬼。。。

 这是他的构造器，他是以requestHandlerSelector为参数的，再去requestHandlerSelector源码中看下。

 再去看下PathSelectors源码

参数是路径，用于过滤。。。

 我们再来看下结果（什么也没扫到，都已经过滤掉了）

8.配置API分组

   @Bean
     public Docket docket(){
         return new Docket ( DocumentationType.SWAGGER_2 )
                 .apiInfo ( apiInfo () )
                 .groupName ( "wdfxfff" )//配置分组
                 .select ()
                 .apis ( RequestHandlerSelectors.basePackage ( "com.example.demo.controller" ) )
                 .paths ( PathSelectors.ant ( "/example/**" ) ).build ();
     }

Docket是Swagger的唯一bean实例，需要什么方法，直接去源码看。。。

 我们再去看看它的默认值是什么？default

 9.实体配置

package com.example.demo.pojo;

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

//@ApiModel用来注释实体类
//@ApiModelProperty用来注释属性值
//@ApiParam用来注释参数
@ApiModel("用户实体")
public class Person {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
    
}

10.Api注释

package com.example.demo.controller;

import com.example.demo.pojo.Person;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
//@ApiOperation给方法加注释
@RestController
public class MyController {
    @GetMapping("/hello")
    @ApiOperation ( "helloSwagger方法" )
    public  String helloSwagger(){
        return "hello";
    }

    @PostMapping("/person")
    public Person helloperson(){
        return new Person ();
    }

    @GetMapping("/hello2")
    @ApiOperation ( "Swagger2方法" )
    public  String Swagger2(@ApiParam("hello参数") String hello){
        return hello;
    }

}

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。Swagger的所有注解定义在io.swagger.annotations包下

这段话的理解请参照狂神说的博客

再来看下测试结果

如何进行测试？

1.Try it out

2.execute

3.方法测试成功，成功输出