spring boot集成Swagger2

第一步：jar包的引入

 <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- 引入swagger-bootstrap-ui包 /doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

 

第二步：swagger的配置启动类

这里有个重点：

1.解决swagger2报错404的问题，没有报错404，则不要继承 WebMvcConfigurationSupport 解决找不到资源的问题

2.我只想开放一部分接口到文档，也就是我打了@ApiOperation的方法就公开在文档，否则不展示

package com.haichuan;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

//swagger2的配置文件，在项目的启动类的同级文件建立
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable",  havingValue = "true")
public class Swagger2 extends WebMvcConfigurationSupport {
    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                //.apis(RequestHandlerSelectors.basePackage("com.haichuan.controller")).paths(PathSelectors.any())
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))          //只扫描有api注解的类
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//只扫描有ApiOperation注解的方法
                .build();
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("系统接口API")
                // 创建人信息
                .contact(new Contact("系统API",  "http://localhost:9001/warranty/doc.html",  "haichuan@163.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述")
                .build();
    }

    //解决swagger2 404的问题
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

 

启动类

 

三、在controller中添加注解

这些注解看实际使用情况自行添加。

@Api：用在类上，说明该类的作用
 
@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了。
 
@ApiImplicitParams：用在方法上包含一组参数说明
 
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面。
 
@ApiResponses：用于表示一组响应
 
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
 
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModelProperty： 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，
对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序。

 

下面罗列下实际开发中最常用的三种写法，注意请求方法必须写。这三种基本够用了。httpMethod这个参数必须设置。

//注解在类上,其实只有这个value值有效
@Api(value="/decorate[装修选型版块Controller]", tags="装修选型版块Controller")

//注解在方法上,注意这个httpMethod必须要写，不然各种请求都会帮你罗列出来
//paramType = "path"这个参数，如果不是请求方法后面直接带参数可以去掉，例如/getUserId/2,这种请求这个参数就需要配置，否则应该去除
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",httpMethod = "GET")//如果没有请求参数，用这个一个就行
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")

//多个请求参数，注意这里就没有 paramType = "path"。
@ApiOperation(value="合作方式", notes="选择合作方式",httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "machinePrcie", value = "购买机械价格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "daystate", value = "按天计算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "overserPrice", value = "按天计算价格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "areastate", value = "按面积计算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "prcie", value = "按面积计算总价", required = true, dataType = "Double")
    })

 

三、安全验证放过swagger相关

实际上线则不能放过，或者相关文档删除，相关接口必须对外保密。

/*swagger*/
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");

 

四、配置文件开启swagger，生产环境关闭

swagger:
  enable: true

 

五、访问：http://localhost:9001/warranty/doc.html