knife4j接口文档工具使用

1简介

我想大家都见过大厂api接口文档页面吧，上面详细的介绍了该接口具体的作用参数响应结果等。今天说说knife4j后端接口文档生成工具。如果想要对类方法等生成文档可以使用apiDoc。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,具有小巧,轻量,功能强悍的特点，其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。

根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，对该接口的使用情况一目了然。

官网地址
https://doc.xiaominfo.com/knife4j/documentation/
或https://www.bookstack.cn/read/knife4j/springmvc-notshow.md

线上版文档示例：

2使用

2.1引入依赖

注意：swagger-bootstrap-ui在2.0版本之后改名为knife4j，Knife4j本身已经引入了springfox-swagger2，无需再引入

2.2与springmvc结合

因为springmvc是拦截静态资源的，需要放行，否则无法访问接口文档

2.3编写Swagger配置文件

这里并没有使用注解的方式实例化，所以需要在spring mvc容器中实例化

2.4Swagger相应注解使用

2.4.1方法注解

2.4.1实体类注解

2.5启动项目

访问地址http://localhost:8081/doc.html

2.6常用注解详解

1、与模型相关的注解

@ApiModel：用在模型类上，对模型类做注释；

@ApiModelProperty：用在属性上，对属性做注释

2、与接口相关的注解

@Api：用在controller上，对controller进行注释；

@ApiOperation：用在API方法上，对该API做注释，说明API的作用；

@ApiImplicitParams：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明；

@ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面，该注解包含的常用选项有：

paramType：参数所放置的地方，包含query、header、path、body以及form，最常用的是前四个。

name：参数名；

dataType：参数类型，可以是基础数据类型，也可以是一个class；

required：参数是否必须传；

value：参数的注释，说明参数的意义；

defaultValue：参数的默认值；

@ApiResponses：通常用来包含接口的一组响应注解，可以简单的理解为响应注解的集合声明；

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：即httpCode，例如400

message：信息，例如"请求参数没填好"

如果并没有线上文档的需要，可以使用apiPost工具，使用apiPost可以免费调试接口编写接口文档，并可以免费下载word

用你发财的小手给个赞和关注，谢谢大家

Tags：apiimplicitparam注解用法