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

 

posted @ 2019-06-03 11:24  别动我的猫  阅读(955)  评论(0)    收藏  举报