依赖
|
1
2
3
4
5
6
7
8
9
10
|
<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> |
配置类
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
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 陈加兵 * */@configurationpublic 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，请求的参数写在路径上，如下：
|
1
2
3
4
5
6
7
8
|
@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, "陈加兵"); } |
-
body：以流的形式提交 仅支持post
form：以表单的形式提交
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持服务器之家。
原文链接：https://chenjiabing666.github.io/2018/10/21/SpringBoot整合Swagger/
