1.Swagger介绍
Swagger用于在类或者方法上通过注解的方式生成API接口,然后使用Swagger-ui这个项目去浏览这些接口,就不用手动的去写word/Excel接口文档了。
这个接口文档因为是通过代码注解生成的,所以是实时体现了接口的变化。另一个重要的功能是,可以基于swagger-ui测试这些接口。
2.实战
1)Maven关键配置
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
2)下载swagger-ui项目,将项目里的dict文件夹copy到web项目的webapp目录下。
3)对想要生成的接口用swagger提供的方法进行注解。
- 类使使用@Api注解
- 方法使用@ApiOperation注解
- 参数使用@ApiParam注解
- 如果方法不想暴露出去,需要用@ApiIgnore注解,否则sagger-ui会对没有标注@ApiIgnore和@ApiOperation的方法对http协议中 GET/POST/DELETE/HEAD/PATCH/PUT/OPTIONS分别生成对对应的方法。
注解后的截图如下:
浏览swagger-ui
如上图,因为/users/query没有使用@ApiIgnore注解,所以被swagger-ui按照http中的协议分别生成了方法。这些接口是可测试的,点击/users/query,可出现如下:
点击试一下,即可调用接口方法。