POM引入插件
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索最新版本号 -->
<version>2.0.3</version>
</dependency>
配置加载
package com.pengsn.apiserver.videoconference.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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;
/**
* 配置
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
// 这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage(
"com.pengsn.apiserver.videoconference.business"))
.paths(PathSelectors.any()).build();
return docket;
}
private ApiInfo apiInfo() {
Contact contact = new Contact("pengsn", "", "");
return new ApiInfoBuilder().title("视频会议接口描述").
description("视频会议接口描述").contact(contact).version("1.0").build();
}
}
访问地址
访问地址是:http://${host}:${port}/doc.html
界面显示
注解使用
-
@Api(tags="controller description"); 作用于 类
-
@ApiOperator(value="接口名称", notes="接口描述") 作用于 方法
-
@ApiOperationSupport(order=1) 排序
2.5 注解
在 swagger-annotations
库中,在 io.swagger.annotations
包路径下,提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的,大多数场景下,只需要使用到我们在 「2.4 UserController」 中用到的注解。
2.5.1 @Api
@Api
注解,添加在 Controller 类上,标记它作为 Swagger 文档资源。
示例如下:
// UserController.java
@RestController
@RequestMapping("/users")
@Api(tags = "用户 API 接口")
public class UserController {
// ... 省略
}
效果如下:
@Api
注解的常用属性,如下:
-
tags
属性:用于控制 API 所属的标签列表。
[]
数组,可以填写多个。
-
可以在一个 Controller 上的 @Api
的 tags
属性,设置多个标签,那么这个 Controller 下的 API 接口,就会出现在这两个标签中。
-
如果在多个 Controller 上的 @Api
的 tags
属性,设置一个标签,那么这些 Controller 下的 API 接口,仅会出现在这一个标签中。
-
本质上,tags
就是为了分组 API 接口,和 Controller 本质上是一个目的。所以绝大数场景下,我们只会给一个 Controller 一个唯一的标签。例如说,UserController 的 tags
设置为 "用户 API 接口"
。
@Api
注解的不常用属性,如下:
-
produces
属性:请求请求头的可接受类型( Accept )。如果有多个,使用 ,
分隔。
-
consumes
属性:请求请求头的提交内容类型( Content-Type )。如果有多个,使用 ,
分隔。
-
protocols
属性:协议,可选值为 "http"
、"https"
、"ws"
、"wss"
。如果有多个,使用 ,
分隔。
-
authorizations
属性:授权相关的配置,[]
数组,使用 @Authorization
注解。
-
hidden
属性:是否隐藏,不再 API 接口文档中显示。
@Api
注解的废弃属性,不建议使用,有 value
、description
、basePath
、position
。
2.5.2 @ApiOperation
@ApiOperation
注解,添加在 Controller 方法上,标记它是一个 API 操作。
示例如下:
// UserController.java
@GetMapping("/list")
@ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试,所以返回用户全列表")
public List<UserVO> list() {
// 查询列表
List<UserVO> result = new ArrayList<>();
result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
result.add(new UserVO().setId(2).setUsername("woshiyutou"));
result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
// 返回列表
return result;
}
效果如下:
@ApiOperation
注解的常用属性,如下:
-
value
属性:API 操作名。
-
notes
属性:API 操作的描述。
@ApiOperation
注解的不常用属性,如下:
-
tags
属性:和 @API
注解的 tags
属性一致。
-
nickname
属性:API 操作接口的唯一标识,主要用于和第三方工具做对接。
-
httpMethod
属性:请求方法,可选值为 GET
、HEAD
、POST
、PUT
、DELETE
、OPTIONS
、PATCH
。因为 Swagger 会解析 SpringMVC 的注解,所以一般无需填写。
-
produces
属性:和 @API
注解的 produces
属性一致。
-
consumes
属性:和 @API
注解的 consumes
属性一致。
-
protocols
属性:和 @API
注解的 protocols
属性一致。
-
authorizations
属性:和 @API
注解的 authorizations
属性一致。
-
hidden
属性:和 @API
注解的 hidden
属性一致。
-
response
属性:响应结果类型。因为 Swagger 会解析方法的返回类型,所以一般无需填写。
-
responseContainer
属性:响应结果的容器,可选值为 List
、Set
、Map
。
-
responseReference
属性:指定对响应类型的引用。这个引用可以是本地,也可以是远程。并且,当设置了它时,会覆盖 response
属性。说人话,就是可以忽略这个属性,哈哈哈。
-
responseHeaders
属性:响应头,[]
数组,使用 @ResponseHeader
注解。
-
code
属性:响应状态码,默认为 200 。
-
extensions
属性:拓展属性,[]
属性,使用 @Extension
注解。
-
ignoreJsonView
属性:在解析操作和类型,忽略 JsonView 注释。主要是为了向后兼容。
@ApiOperation
注解的废弃属性,不建议使用,有 position
。
2.5.3 @ApiImplicitParam
@ApiImplicitParam
注解,添加在 Controller 方法上,声明每个请求参数的信息。
示例如下:
// UserController.java
@PostMapping("/delete")
@ApiOperation(value = "删除指定用户编号的用户")
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
public Boolean delete(@RequestParam("id") Integer id) {
// 删除用户记录
Boolean success = false;
// 返回是否更新成功
return success;
}
效果如下:
@ApiImplicitParam
注解的常用属性,如下:
-
name
属性:参数名。
-
value
属性:参数的简要说明。
-
required
属性:是否为必传参数。默认为 false
。
-
dataType
属性:数据类型,通过字符串 String 定义。
-
dataTypeClass
属性:数据类型,通过 dataTypeClass
定义。在设置了 dataTypeClass
属性的情况下,会覆盖 dataType
属性。推荐采用这个方式。
-
paramType
属性:参数所在位置的类型。有如下 5 种方式:
-
"path"
值:对应 SpringMVC 的 @PathVariable
注解。
-
【默认值】"query"
值:对应 SpringMVC 的 @PathVariable
注解。
-
"body"
值:对应 SpringMVC 的 @RequestBody
注解。
-
"header"
值:对应 SpringMVC 的 @RequestHeader
注解。
-
"form"
值:Form 表单提交,对应 SpringMVC 的 @PathVariable
注解。
-
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)