Swagger学习
采用swagger ui可实现接口可视化，脱离写接口文档的痛苦，及避免不厌其烦地解说各接口需要的参数和返回结果
一、什么是swagger
Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。
二、swagger的优势
1.整体文档界面清晰易看
使用swagger生成的接口文档直观可视，脱离写接口文档的痛苦，及避免不厌其烦地解说各接口需要的参数和返回结果
2. 接口文档的查看简单易懂
接口路径查看
需要传递的参数查看
调用成功后返回的json数据有什么参数，参数的意思的什么的查看
3. 接口测试便利
接口测试，只需填好传参，然后点击Try it out！按钮即可
三、Swagger整合springMVC
1.依赖管理
|
|
2. Swagger配置
Swagger的配置实际上就是自定义一个Config类，通过java编码的方式实现配置。代码如下：
|
@Configuration @EnableSwagger public class SwaggerConfig { private SpringSwaggerConfig springSwaggerConfig; @Autowired public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; /* * Spring在启动的时候检测到@Bean的时候默认会在容器中注入一个以方法名（你的代码中是user）命名的Bean，而这个Bean用的是和该方法的返回类型一样的类（你的代码中是User）来初始化的。 */ @Bean public SwaggerSpringMvcPlugin customImplementation(){ return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) .apiInfo(apiInfo()) .enable(ConfigUtil.getInstance().getBoolean("enableSwagger"))//用于控制设置使用swagger .includePatterns(".*?"); private ApiInfo apiInfo(){ return new ApiInfo(ConfigUtil.getInstance().get("project.name"),"接口文档",null,ConfigUtil.getInstance().get("email"),null,null); |
其中配置文件信息
|
#swagger 参数信息 enableSwagger=true project.name=swagger email=swagger@163.com |
然后，将该配置交给spring管理，在springmvc的配置文件中加入以下配置
|
|
或可通过扫描注入
自定义操作对象的接口方法
|
@Api(value="test-doc",description="用于测试") @Controller @RequestMapping("/test") public class TestController { @Autowired private CustomerService customerService; @RequestMapping(value="/get", method = RequestMethod.GET) @ApiOperation(value="根据用户名获取对象",notes="获取对象") public @ResponseBody CustomResult get( @ApiParam("电话号码，必选") @RequestParam(value="phone",required=true)String phone) { //Customer customer = customerService.findByPhone(phone); Customer customer = new Customer(); customer.setName("he"); return CustomResult.ok(customer); @RequestMapping(value="/find", method = RequestMethod.POST) @ApiOperation(value="根据用户名获取对象",notes="获取对象") @ApiResponses({ @ApiResponse(code=Constance.BASE_SUCCESS_CODE,message="成功",response=Customer.class), @ApiResponse(code=Constance.BASE_FAIL_CODE,message="失败",response=String.class) }) public @ResponseBody CustomResult find( @ApiParam("电话号码，必选") @RequestParam(value="phone",required=true)String phone) { //Customer customer = customerService.findByPhone(phone); Customer customer; try { customer = new Customer(); customer.setName("he"); } catch (Exception e) { // TODO Auto-generated catch block e.printStackTrace(); return CustomResult.build(Constance.BASE_FAIL_CODE, Constance.map.get(Constance.BASE_FAIL_CODE)); return CustomResult.ok(customer); } } |
3. Swagger ui配置
从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入 WebRoot/static/swagger/ 目录下。
修改swagger/index.html文件，并将其放在WebRoot下，如下
因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以在springmvc配置文件中需要配置对静态文件的处理方式。
|
|
打开浏览器直接访问项目下的index.html文件，即可看到接口文档说明了
四、Swagger的使用
整合好项目
然后就放进tomcat，启动
路径通常是:项目名+/api.html
这个就是写好的api，分别对应是以下这样
填好要传的参数，然后try it out按钮就能进行接口测试
客户端返回状态码
然后在Api接口添加这些
下面就是实体类的参数中文说明