springboot集成swagger

项目目录结构和上一文章章一致：springboot通过mybatis连接数据库

一、SpringBoot引入Swagger的两种方式

1.引入 swagger 原生依赖 springfox-swagger2 和 springfox-swagger2-ui
2.引入国内 Spring4All 社区开发的依赖 swagger-spring-boot-starter

第一种是通过Java代码配置的，第二种可以在配置文件配置比较方便。

本文对第一种方式进行介绍，第二种请参考：SpringBoot整合Swagger实战

二、引入相关依赖

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

个人习惯了2.9.2版本的界面（低版本的界面看着不习惯。。。）：

2.9.2版本的界面：

三、相关代码和配置

项目结构：

1.Controller：

package com.springboot.demo.test.userController;

import com.springboot.demo.test.dao.Userdao;
import com.springboot.demo.test.model.TestModel;
import com.springboot.demo.test.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@Api(tags  = "查询相关的")
@RestController
@RequestMapping(value = "/query")
public class Usercontroller {
    @Autowired
    Userdao userdao;
    @Autowired
    UserConsumer userConsumer;

    @ApiOperation("列表查询")
    @GetMapping(value = "/v1/findAll")
    public List<User> query(@ApiParam(value = "学生id" , required=true ,example = "1") @RequestParam int id) {
        return userdao.findAll();
    }

    @ApiOperation("计算a+b")
    @GetMapping(value = "/v1/add")
    public int query(@ApiParam(value = "这是a") @RequestParam int a,@ApiParam(value = "这是b")@RequestParam int b ) {
        return a+b;
    }

	@ApiOperation("get请求测试")
    @GetMapping(value = "/v1/getBaiDuRequest")
    public int getRequest(@ApiParam(value = "入参JSON") AdditionModel additionModel) {
        return userConsumer.getRequest(additionModel);
    }

    @ApiOperation("测试")
    @PostMapping(value = "/v1/test")
    public List<User> query(@ApiParam(value = "入参JSON") @RequestBody TestModel testModel ) {
        return userdao.findAll();
    }
}

注意：如果是post接口参数前要加@RequestBody（@RequestBody是作用在形参列表上，用于将前台发送过来固定格式的数据xml格式 或者 json等封装为对应的 JavaBean 对象），参考：@ResponseBody详解

2.swagger的配置文件SwaggerConfig：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.service.AuthorizationScope;
import java.util.ArrayList;
import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

/**
 * SwaggerConfig
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build()
                .securitySchemes(unifiedAuth())
                .securityContexts(securityContexts());
    }

    //swagger页面信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("我的API接口文档")
                .description("如若没有火炬，我便是唯一的光")
                .version("1.0")
                .build();
    }

    //authorizations token设置
    private static List<ApiKey> unifiedAuth() {
        List<ApiKey> arrayList = new ArrayList();
        arrayList.add(new ApiKey("app-token", "app-token", "header"));
        return arrayList;
    }

    private static List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.any())
                        .build()
        );
    }

    //authorizations全局设置（设置了token后所有接口生效）
    private static List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global","accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("app-token",authorizationScopes));
    }

    /**
     * 设置过滤规则
     * 这里的过滤规则支持正则匹配
     * @return
     */
/*    private Predicate<String> doFilteringRules() {
        return or(
                regex("/hello.*"),
                regex("/vehicles.*")
        );
    }*/
}

3.TestModel：

package com.springboot.demo.test.model;

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

@ApiModel(description = "学生基本查询条件")
public class TestModel {
    @ApiModelProperty(notes = "客户号")
    private String id;
    @ApiModelProperty(notes = "姓名")
    private String name;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

四.启动后最终效果

因为我的配置文件中启动端口配置成了8083

server:
  port: 8083

所以启动 http://localhost:8083/swagger-ui.html#/

其他参考文章：
SpringBoot整合Swagger实战
Spring Boot：整合Swagger文档
spring-boot-swagger2 使用手册
swagger2 注解说明 ( @ApiImplicitParams )
解决访问swaggerUI接口文档显示basic-error-controler问题