如何优雅的“编写”api接口文档
前言
今天我需要把之前写的接口整理成文档,老大给了意见用swagger搞,我像发现新大陆一样的兴奋,迫不及待得去“占有”它。
Swagger
很容易上手,我花了十几分钟就搞定了。正好接着之前的如何优雅的格式化接口,这里再说一下SpringBoot整合Swagger的简单过程吧
Swagger介绍
每每get新的技能想分享的时候,按照套路来讲,需要有一个版块将该技能的“前世今生”介绍个遍,但就我接触到完成配置不超过半小时,我觉得让我完完整整的介绍有点太虚了,所以,最好的介绍就是下面的官网
http://swagger.io/
http://swagger.io/irc/ 这个是实时聊天室,刚刚和老外沟通了一番“how are you?fine thk you.and you?”
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel 这个是一些注解的api
Swagger有三个模块
- Swagger Editor
- Swagger UI
-
Swagger Codegen
我使用的是Swagger UI,我个人的理解就是“使用Swagger相关的注解并启动服务后,就可以在对应的页面查看API并测试”,先看一下最终的界面
接口描述、参数类型、返回示例在线调试都给你搞定了。你还在犹豫什么,赶快checkou代码,试一试吧
整合
我接着之前的代码的写(可以在我的GitHub上浏览,或者直接clone到本地再切换到api-norms分支),这里要说一下,使用Springboot整合Swagger贼JB简单,相比较而言,SpringMVC就比较复杂了,这里暂且不谈(以后可能也不会谈了,自从我使用了Springboot之后,就已经开始抛弃SpringMVC了)
maven依赖
老规矩上配置
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
添加Swagger
注解
在Application上直接添加@EnableSwagger2
,注意版本,官网上的版本还没有更新到最新的,最新的在Github上看,配置后的代码
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Created by wangxc on 2017/3/9.
*/
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
可以了,接下来就是描述接口的注解了!在Controller层,做如下配置
package com.quick.api;
import com.quick.po.Address;
import com.quick.utils.BaseResp;
import com.quick.utils.ResultStatus;
import io.swagger.annotations.*;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
/**
* Created with IDEA
* User: vector
* Data: 2017/4/12
* Time: 8:41
* Description:
*/
@RestController
@RequestMapping("/api")
@Api("springboot整合swagger2") // Swagger UI 对应api的标题描述
public class WebController {
@ApiOperation("获取地址信息") // 单个接口的描述
@ApiImplicitParams({
@ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="广东省"),// 每个参数的类型,名称,数据类型,是否校验,描述,默认值(这些在界面上有展示)
@ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地区",defaultValue="南山区"),
@ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃园路"),
@ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="门牌号",defaultValue="666")
})
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"), // 响应对应编码的描述
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@RequestMapping(value = "/address",method = RequestMethod.POST)
public BaseResp<Address> getAddressInfo(@RequestParam(value = "province")String province,
@RequestParam(value = "area")String area,
@RequestParam(value = "street")String street,
@RequestParam(value = "num")String num){
if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
return new BaseResp(ResultStatus.error_invalid_argument);
}
Address address = new Address();
address.setProvince(province);
address.setArea(area);
address.setStreet(street);
address.setNum(num);
return new BaseResp(ResultStatus.SUCCESS,address);
}
@ApiOperation("获取地址信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="广东省"),
@ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地区",defaultValue="南山区"),
@ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃园路"),
@ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="门牌号",defaultValue="666")
})
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@RequestMapping(value = "/address/list",method = RequestMethod.POST)
public BaseResp<List<Address>> getAddressList(@RequestParam(value = "province")String province,
@RequestParam(value = "area")String area,
@RequestParam(value = "street")String street,
@RequestParam(value = "num")String num){
if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
return new BaseResp(ResultStatus.error_invalid_argument);
}
Address address = new Address();
address.setProvince(province);
address.setArea(area);
address.setStreet(street);
address.setNum(num);
List<Address> lists = new ArrayList<>();
lists.add(address);
lists.add(address);
lists.add(address);
return new BaseResp(ResultStatus.SUCCESS,lists);
}
}
- 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
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
- 75
- 76
- 77
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 89
- 90
我只是在原来的基础上添加了下面注解
名称 | 解释 |
---|---|
@Api() | 将类标记为一种Swagger资源。 |
@ApiOperation() | 描述针对特定路径的操作或通常是 http 方法。 |
@ApiImplicitParams | 允许多个 ApiImplicitParam 对象列表的包装。 |
@ApiImplicitParam | 表示 api 操作中的单个参数。 |
@ApiResponses | 允许多个 ApiResponse 对象列表的包装。 |
@ApiResponse | 描述操作的可能响应。 |
更多的看这里
就这么简单,一个基本而又强大的API文档就整理好了!
启动
正常的启动SpringBoot,你会发现控制台输出了这些内容
2017-05-03 21:42:52,975 INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
2017-05-03 21:42:52,986 INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
- 1
- 2
说明Swagger已经成功跑起来了,接下来打开浏览器,输入你链接
yourdomain/swagger-ui.html
我的是http://localhost:8080/swagger-ui.html
相信你看了界面并四处点点之后,就会对上面注解的含义有了更进一步的了解~
后记
这里展示的只是Swagger最基本的功能,更多强大的功能如果后面有运用,我会持续更新的。
目前我在看api寻找SwaggerUI输入文件的测试,因为我有个接口需要上传文件,等我搞定,再来分享吧!!!
欢迎进入我的个人博客浏览
上一篇: python全局变量
下一篇: 有关sort()的文章推荐10篇
推荐阅读
-
PHP如何使用JWT做Api接口身份认证的实现
-
yii2 开发api接口时优雅的处理全局异常的方法
-
.NET Core利用swagger进行API接口文档管理的方法详解
-
[编写高质量iOS代码的52个有效方法](五)接口与API设计(下)
-
如何将你的python程序制作为第三方API接口可供任何人调用
-
用Node编写RESTful API接口的示例代码
-
如何查看jsplumb.js的API文档(YUIdoc的基本使用)
-
golang如何优雅的编写事务代码示例
-
如何优雅的将文件转换为字符串(环绕执行模式&行为参数化&函数式接口|Lambda表达式)
-
比最差的API(ETW)更差的API(LTTng)是如何炼成的, 谈如何写一个好的接口