为了方便的管理项目中API接口,目前总是会写好接口后,然后又要去维护一个文档,这对于开发者来说太心累了,
在网上找了好多关于API接口管理和生成文档的资料,一次偶然跟51的大神交流发现了Swagger这个工具,功能强大,UI界面漂亮,并且支持在线测试等等,
对于这块的使用网上已经有很多教程,我这里用的跟网上的那些不太一样,部署好后遇到的问题的解决方式也不一样,
这里只谈要注意的地方和问题
先上今天直接摸索出来的效果图:
详细的请求api接口如下图
这里我只是测试,用api配置了一个接口。然后Swagger自动生成出来了,包括以往的接口名都生成出来了,只是要参数详细还得详细配置,这段代码是我参照网上的直接copy过来
@RequestMapping(value= "/1.0/contact/update.do/{id}",method=RequestMethod.POST)
@ApiResponses (value = {
@ApiResponse (code = 200, message = "更新成功", response = Contact. class),
@ApiResponse (code = 404, message = "Not Found"),
@ApiResponse (code = 500, message = "内部报错")}
)
public void update( @ApiParam (name= "id", value= "编号", required= true) @PathVariable Integer id, @RequestBody Contact contact) {
contact.setId(id);;
contactService.update(contact);
}
我这里不详细介绍了,
想了解的直接 http://blog.csdn.net/zth1002/article/details/46927187
首先引入这些包
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.4.4</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.3</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-staticdocs</artifactId>
<version>2.2.2</version>
<scope>test</scope>
</dependency>
这些pom包里面包括ui静态资源,引入后就不用去git下载ui静态资源了
第二需要注意的,就是写一个SwaggerConfig ,然后加上注解配置开启如图
如不会看这里http://blog.csdn.net/zth1002/article/details/46927187
这里的配置好弄,支持正则匹配。如果你觉得太复杂,就直接像我这样配置就可以了,appinfo里面可以配置文档的各种属性。
第三个需要注意的。是SwaggerConfigUi资源里面对mvc-controller的访问是直接这样 /swagger-resources ,
这对于我们设定了指定后缀的mvc-action 来说,就识别不到了,web系统会报404错误,也就是说UI资源里面的html对动态action的请求是不带后缀的
除了这个/swagger-resources,还有一个apidoc 也是请求的一个controller,但是没带后缀系统找不到
那这里再给它在web。xml里面配置url映射。
请求 http://localhost:8080//swagger-ui.html#/ 可以直接访问了
当然也可以后面给它加上权限