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