Swaggr 使用帮助

官网：http://swagger.io/

Annotations文档：
https://github.com/swagger-api/swagger-core/wiki/Annotations
编写API规格文档：http://swagger.io/specification/
开源集成：http://swagger.io/open-source-integrations/
在线编辑：http://editor.swagger.io/#!/

正常开发流程：
通过在线编辑工具编辑API，然后导出服务端和客户端代码进行开发。

swagger+spring boot

如果是spring mvc集合，则使用springfox,官网Demo，如果使用Restlet API and JAX-API，则使用restlet-framework

参考文章：
官网博客：https://www.easyitblog.info/2017/01/08/api-first-approach-with-swagger/
其他博客：
http://www.cnblogs.com/java-zhao/p/5348113.html
https://juejin.im/entry/580457030bd1d0005812a700
http://www.cnblogs.com/woshimrf/p/5863318.html

编写Controller注意事项

1. 入参最好使用Spring MVC提供的注解：@RequestBody,@RequestParam,@PathVariable，取代使用HttpServletRequest request.getParamter()的方式，因为使用request.getParamter这种方式获取参数时，swagger无法自动解析出入参对象。
2. 如果Controller入参为对象，不加@RequestBody和加上@RequestBody的区别：
   
   

   Paste_Image.png
   
   打开swagger-ui：
   添加有@RequestBody注解的入参为一个json串对象：
   
   

   添加有RequestBody注解
   
   没有RequestBody注解的为不同的字段：
   
   

   没有RequestBody注解
3. 出参尽量使用@ResponseBody或者RespinseEntity对象。区别：ResponseEntity可以包含Header和HttpStatus。
4. 入参使用注解时，根据是否必填修改requested值。

swagger常用路径

1. swaggerUI路径：http://localhost:8080/swagger-ui.html
2. swagger API路径查看：http://localhost:8080/swagger-resources
   
   

   Paste_Image.png
3. swagger API 说明文件查看。根据2结果，查询对应api的json，例如查询full-demo-api，这它对应的location为/v2/api-docs?group=full-demo-api，这路径为：http://localhost:8080/v2/api-docs?group=full-demo-api

使用现有Controller生成客户端文件

首先通过swagger UI查询出该API对应的json说明文件，方式为上面“swagger常用路径”第3个，例如为：http://localhost:8080/v2/api-docs?group=full-demo-api， 浏览器中打开：

full-demo-api

复制结果，打开swagger editor,选择File-->Paste JSON,将内容复制进去点击Import。

Paste_Image.png

然后选择GenerateServer或GenerateClient选择对应的语言下载即可，可以下载为HTML。

Paste_Image.png

swagger转为HTML 和 PDF文档

请查看：http://www.jianshu.com/p/0aa7c915ee9e

Eclipse插件:RepreZen API Studio（收费，可以试用14天）
官网：http://www.reprezen.com/Swagger-Tools
已经上架Eclipse Marketplace