SpringBoot整合Swagger的方法示例

所属分类：软件编程 / java 阅读数： 19

收藏 0赞 0分享

依赖

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

配置类

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger的配置类
 * @author 陈加兵
 *
 */
@Configuration
public class SwaggerConfig{
 /**
 * 创建用户API文档
 * @return
 */
 @Bean
 public Docket createRestUserApi(){
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("user") 
 .apiInfo(apiInfo()) //api的信息
 .select()
 .apis(RequestHandlerSelectors
  .basePackage("cn.tedu.mycat.controller")) //添加包扫描
 .paths(PathSelectors.any()).build();

 }

 /**
 * 创建API信息
 */
 private ApiInfo apiInfo(){
 return new ApiInfoBuilder()
 .title("api文档的标题") //标题
 .description("api文档的描述") //描述
 .contact( //添加开发者的一些信息
  new Contact("爱撒谎的男孩", "https://chenjiabing666.github.io",
  "18796327106@163.com")).version("1.0").build();
 }

}

启动类

在springBoot的启动类上添加一个注解即可配置成功： @EnableSwagger2

访问api的路径
http://ip/projectName/swagger-ui.html

注解说明

@Api

标注在类上，用来对这个类进行说明的
如果想要生成文档，必须在类或者接口上标注
属性如下：

属性名称	备注	默认值
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation

用在API方法上，对该API做注释，说明API的作用
不需要多讲，看源码，使用默认的value属性即可，说明该方法的作用
属性如下：

value	url的路径值
tags	如果设置这个值、value的值会被覆盖
notes	对api资源的描述
response	返回的对象，在文档中点击Model可以获取该配置的内容
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
responseReference	可以不配置
httpMethod	可以接受 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
position	如果配置多个Api 想改变显示的顺序位置
produces	同 Api中的定义
consumes	同 Api中的定义
protocols	同 Api中的定义
authorizations	同 Api中的定义
hidden	是否隐藏，true 或者false ，这个可以隐藏后台接口
code	http的状态码默认 200
extensions	扩展属性

@ApiImplicitParams

用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明
很重要，这个注解其中包含接口入参的详细说明
内容是集合

@ApiImplicitParam

用在 @ApiImplicitParams 注解中，也可以单独使用，说明一个请求参数的各个方面

详细的属性使用说明如下：

name ：属性的字段名称，相当于form表单中的name，这个就是入参的字段
dataType ：参数的类型，标识，字符串
value ：该参数的描述
required ：是否必填，布尔值
defaultValue ：缺省值，会在文档中缺省填入，这样更方面造数据，不需要调用接口的去填值了
paramType ：指定参数的入参数方式（也就是请求参数的位置），其中有四种常用的，如下：
- query
- path
- body
- form

paramType属性的详细说明

query ：必须要和入参的字段一样，也可以使用 @RequestParam() 指定
path ：用于Restful的风格的url，请求的参数写在路径上，如下：

@ApiOperation(value="根据用户Id获取用户信息",response=User.class,hidden=false)
 @ApiImplicitParams({
 @ApiImplicitParam(paramType = "path", name = "id", dataType="Integer", required = false, value = "用户的id", defaultValue = "1")
 })
 @GetMapping("/user/get/{id}")
 public Object getUser(@PathVariable("id")Integer id){
 return new User(id, "陈加兵");
 }