Swagger2
Swagger2 整合 Springboot
地址:https://blog.csdn.net/simba1949/article/details/80919183
什么是swagger2
编写和维护接口文档是每个程序员的职责,根据 Swagger2 可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
Swagger2 配置类
代码
package top.simba1949.config;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2 配置类
* @Configuration 让 Spring 容器加载该配置类
* @EnableSwagger2 用于启动 swagger2
* @author simba@onlying.cn
* @date 2018/7/4 21:36
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* swagger2 启动后,通过createRestApi函数创建Docket的Bean,
* apiInfo() 用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
* select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("top.simba1949.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("springboot学习笔记")
.termsOfServiceUrl("http://localhost:8080/")
.version("1.0")
.build();
}
}
效果
常用注解
-
@Api:修饰整个类,描述Controller的作用
-
@ApiOperation:描述一个类的一个方法,或者说一个接口
-
@ApiParam:单个参数描述
-
@ApiModel:用对象来接收参数
-
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
-
@ApiIgnore:使用该注解忽略这个API,用于类或者方法上
-
@ApiImplicitParam:一个请求参数,用于方法上
-
@ApiImplicitParams:多个请求参数 ,包含多个 @ApiImplicitParam,用于方法上
@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解,如果tags多个值,会生成多个list" value="该参数没什么意义,在UI界面上也看不到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiParam:单个参数描述 - name:参数名 - value:参数说明 - required:是否必填 @ApiModel:用对象来接收参数 - value:表示对象名 - description:对对象的描述 @ApiModelProperty:用对象接收参数时,描述对象的一个字段 - value:字段说明 - name:重写属性名 - dataType:重写属性类型 - example:举例说明 - hidden:隐藏 @ApiIgnore:使用该注解忽略这个API,用于类或者方法上 @ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 name:参数名 value:参数的汉字说明、解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值
@Api:
修饰整个类,描述Controller的作用
- @Api
- tags:对类的说明
代码
/**
* @Api
* value="不会再界面显示出来"
* tags="说明该类的作用,可以在UI界面上看到的注解,如果tags多个值,会生成多个list"
* @date 2018/7/4 20:17
*/
@Api(tags = {"用户操作接口"})
@Controller
@RequestMapping("/user")
public class UserController {
}
效果
@ApiOperation:
描述一个类的一个方法,或者说一个接口
- @ApiOperation
- value:用于方法描述
- notes:用于提示内容
代码
@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@PathVariable String data){
return ResponseBuilder.buildSuccessResponse(data);
}
效果
@ApiParam:
用于单个参数描述
- @ApiParam
- name:参数名
- value:参数说明
- required:是否必填
代码
@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@ApiParam(name = "data",value = "参数说明",required = true)@PathVariable String data){
return ResponseBuilder.buildSuccessResponse(data);
}
效果
@ApiModel & @ApiModelProperty
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
- @ApiModel:用对象来接收参数
- value:表示对象名
- description:对对象的描述
- @ApiModelProperty:用对象接收参数时,描述对象的一个字段
- value:字段说明
- name:重写属性名
- dataType:重写属性类型
- example:举例说明
- hidden:隐藏
代码
package top.simba1949.common;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @author simba@onlying.cn
* @date 2018/7/4 20:18
*/
@ApiModel(value = "用户的POJO",description = "对对象的描述")
public class UserCommon {
@ApiModelProperty(value = "用户Id",name = "userId",dataType = "int",required = true,example = "1",hidden = true)
private int userId;
@ApiModelProperty(value = "用户名",name = "username",dataType = "String",required = true,example = "李白")
private String username;
@ApiModelProperty(value = "用户年龄",name = "age",dataType = "int",required = true,example = "888")
private int age;
@ApiModelProperty(value = "用户密码",name = "password",dataType = "String",required = true,example = "19491001")
private String password;
// getter/setter方法省略
}
效果
@ApiIgnore:
使用该注解忽略这个API,用于类或者方法上
@ApiImplicitParams & @ApiImplicitParam
@ApiImplicitParams :多个请求参数 ,用于方法上,包含多个 @ApiImplicitParam
@ApiImplicitParam:一个请求参数,用于方法上
- @ApiImplicitParam
- name:参数名
- value:参数说明
- dataType:参数类型,默认String,其他值dataType=“Integer”
- paramType:参数发在哪个地方
- header:请求参数的获取 @RequestHeader
- query:请求参数的获取 @RequestParam
- path:请求参数的获取 @PathVariable
- body(不常用)
- form (不常用)
- required:是否必须填写
- defaultValue:默认值
代码
@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法,提示内容")
@ApiImplicitParams({
@ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
@ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
@PostMapping("/query/{data}/{i}")
@ResponseBody
public ResponseCommon query(@PathVariable String data,@PathVariable int i){
return ResponseBuilder.buildSuccessResponse(data + i);
}