springboot集成Swagger2

Swagger简介

Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

而我们于springboot集成的是Swagger2，所以它与swagger有什么区别
Swagger2(springfox-swagger2)是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。

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

SpringBoot集成Swagger2

这是我项目目录

首先导入pom依赖

		<!--Swagger2-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.0</version>
		</dependency>

Swagger2Config（基本配置信息）

package com.xy.springboot02.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @author 阳某
 * @create 2019-11-10 17:38
 */

@Configuration
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2Config {

    /*是否开启swagger*/
    private Boolean enable = true;

    /**
     * @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     */
    @Bean
    public Docket createRestApi() {
        // 为swagger添加header参数可供输入
        ParameterBuilder userTokenHeader = new ParameterBuilder();
        ParameterBuilder userIdHeader = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        userTokenHeader.name("headerUserToken").description("userToken")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        userIdHeader.name("headerUserId").description("userId")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        pars.add(userTokenHeader.build());
        pars.add(userIdHeader.build());

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                //是否开启swagger，正式环境一般是需要关闭的
                .enable(enable)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xy.springboot02.controller"))
                .paths(PathSelectors.any()).build()
                .globalOperationParameters(pars);
    }

    /**
     *
     * - swagger.title=标题
     * - swagger.description=描述
     * - swagger.version=版本
     * - swagger.license=许可证
     * - swagger.licenseUrl=许可证URL
     * - swagger.termsOfServiceUrl=服务条款URL
     * - swagger.contact.name=维护人
     * - swagger.contact.url=维护人URL
     * - swagger.contact.email=维护人email
     * - swagger.base-package=swagger扫描的基础包，默认：全扫描
     * - swagger.base-path=需要处理的基础URL规则，默认：/**
     * - swagger.exclude-path=需要排除的URL规则，默认：空
     * - swagger.host=文档的host信息，默认：空
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题
                .title("SpringBoot02接口文档")
                //文档描述
                .description("测试Swagger2")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact("阳某")
                //版本号
                .version("1.0。0")
                .build();
    }

}

HelloController（控制器）

package com.xy.springboot02.controller;

import com.xy.springboot02.model.Book;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

/**
 * @author 阳某
 * @create 2019-11-09 11:02
 */
@RestController
@RequestMapping("/demo")
@Api(value = "测试Swagger2接口", tags = "HelloController", description = "测试druid相关")
public class HelloController {

    @RequestMapping("/hello1")
    @ApiOperation(value = "测试方法1", notes = "测试方法1")
    @ApiImplicitParam(name = "书籍实体类", value = "书籍实体类", required = true, dataType = "Book", paramType = "query")
    public String say1(Book book){
        return "你好1";
    }

    @RequestMapping("/hello2")
    @ApiOperation(value = "测试方法2", notes = "测试方法2")
    public String say2(){
        try {
            Thread.sleep(2000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        return "你好2";
    }


    /**
     * ApiIgnore 使用该注解忽略这个API，不会生成接口文档。可注解在类和方法上
     * @return
     */
    @ApiIgnore
    @RequestMapping("/hello3")
    @ApiOperation(value = "测试方法3", notes = "测试方法3")
    public String say3(){
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        return "你好3";
    }


}

启动类

package com.xy.springboot02;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@MapperScan("com.xy.springboot02.mapper")
@EnableTransactionManagement
@SpringBootApplication
public class Springboot02Application {

	public static void main(String[] args) {
		SpringApplication.run(Springboot02Application.class, args);
	}
}

常用注解说明

@Configuration标注在类上，相当于把该类作为spring的xml配置文件中的，作用为：配置spring容器(应用上下文)。用@Bean标注方法等价于XML中配置bean。

@EnableSwagger2的作用是启用Swagger2相关功能。

Docket对象包含三个方面信息：

整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。
指定生成API文档的包名。
指定生成API的路径。

@Api：用于controller类上，说明该类的作用

tags	“说明该类的作用，可以在UI界面上看到的注解”
value	“该参数没什么意义，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在controller的方法上，用来说明方法用途、作用

value	“说明方法的用途、作用”
notes	“方法的备注说明”

@ApiImplicitParam：用来给方法入参增加说明
name：参数名

value：参数的汉字说明、解释

dataType： 参数类型，默认String

required ： 参数是否必传，true必传

defaultValue：参数的默认值

paramType：参数放在哪个地方

header请求参数的获取:@RequestHeader,参数从请求头获取

query请求参数的获取:@RequestParam,参数从地址栏问号后面的参数获取

path（用于restful接口）请求参数的获取：@PathVariable，参数从URL地址上获取

body（不常用）参数从请求体中获取

form（不常用）参数从form表单中获取

@ApiImplicitParams：用在controller的方法上，一组@ApiImplicitParam
@ApiResponse：用在 @ApiResponses里边，一般用于表达一个错误的响应信息
code：数字，例如400

message：信息，例如"请求参数没填好"

response：抛出异常的类

@ApiResponses：用在controller的方法上，用于表示一组响应
@ApiModel：用在返回对象类上，描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody，请求参数无法使用)
value = 字段说明
name = 重写属性名字
dataType = 重写属性类型
required = 是否必填，true必填
example = 举例说明
hidden = 隐藏

@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在出入参数对象的字段上，表示对model属性的说明或者数据操作更改
@ApiIgnore：使用该注解忽略这个API，不会生成接口文档。可注解在类和方法上

启动项目后，输入http://localhost:8080/swagger-ui.html访问，页面如下

这样API就给你生成好了
end…