简介

号称：世界最流行的API框架

官网：http://swagger.io/

解决什么问题：在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档。

实例代码位置：https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger

swagger使用方式

第一种

定义YAML文件，然后可以生成各种语言的代码框架，对于后台程序员来说，较少人会愿意写出一堆YAML格式。

第二种

swagger有各种语言的插件，可以通过配置及少量代码，生成接口文档及测试界面。

我们多做了：一次性的配置及少量注解代码。

我们不用再做：1、到Wiki中更新接口文档；2、Postman形式的测试；3、Curl形式的测试

swagger java使用介绍

对于一个SpringMVC项目，使用swagger的配置如下：

pom.xml

[html]  view plain  copy

 

 print?

1. <!-- Swagger -->  
2. <dependency>  
3.     <groupId>io.swagger</groupId>  
4.     <artifactId>swagger-core</artifactId>  
5.     <version>1.5.8</version>  
6. </dependency>  
7. <dependency>  
8.     <groupId>io.springfox</groupId>  
9.     <artifactId>springfox-swagger2</artifactId>  
10.     <version>2.4.0</version>  
11. </dependency>  
12. <dependency>  
13.     <groupId>io.springfox</groupId>  
14.     <artifactId>springfox-swagger-ui</artifactId>  
15.     <version>2.4.0</version>  
16. </dependency>  

SwaggerConfiguration.java

[java]  view plain  copy

 

 print?

1. @Configuration  
2. @EnableSwagger2  
3. public class SwaggerConfiguration {  
4.     @Bean  
5.     public Docket api() {  
6.         return new Docket(DocumentationType.SWAGGER_2)  
7.                 .select()  
8.                 .apis(RequestHandlerSelectors.any())  
9.                 .paths(PathSelectors.any())  
10.                 .build();  
11.     }  
12. }  

SwaggerWebMvcConfigurerAdapter.java

[java]  view plain  copy

 

 print?

1. @Configuration  
2. @EnableWebMvc  
3. @ComponentScan(basePackages = "com.xx.travel.csc.stat.controller")  
4. public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {  
5.    
6.     @Bean  
7.     public ViewResolver viewResolver() {  
8.         InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();  
9.         viewResolver.setViewClass(JstlView.class);  
10.         viewResolver.setPrefix("/WEB-INF/views/");  
11.         viewResolver.setSuffix(".jsp");  
12.         return viewResolver;  
13.     }  
14.    
15.     @Bean  
16.     public MessageSource messageSource() {  
17.         ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();  
18.         messageSource.setBasename("messages");  
19.         return messageSource;  
20.     }  
21.     @Override  
22.     public void addResourceHandlers(ResourceHandlerRegistry registry) {  
23.         super.addResourceHandlers(registry);  
24.         registry.addResourceHandler("swagger-ui.html")  
25.                 .addResourceLocations("classpath:/META-INF/resources/");  
26.         registry.addResourceHandler("/webjars/**")  
27.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");  
28.     }  
29.     @Override  
30.     public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {  
31.         configurer.enable();  
32.     }  
33. }  

Controller实例

然后，只要在我们的Controller里面增加注解 ApiOperation和ApiParam 即可。

[java]  view plain  copy

 

 print?

1. @Controller  
2. @RequestMapping(value = "/stat")  
3. public class SwaggerController {  
4.        
5.     @ResponseBody  
6.     @RequestMapping(value = "/helloworld", method = RequestMethod.GET)  
7.     @ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "测试HelloWorld")  
8.     public String helloWorld(@ApiParam(value = "昵称") @RequestParam String nickname) {  
9.         return "Hello world, " + nickname;  
10.     }  
11.        
12.     @ResponseBody  
13.     @RequestMapping(value = "/objectio", method = RequestMethod.POST)  
14.     @ApiOperation(nickname = "swagger-objectio", value = "Swagger的ObjectIO", notes = "测试对象输入输出")  
15.     public SwaggerOutput objectIo(@ApiParam(value = "输入") @RequestBody SwaggerInput input) {  
16.         SwaggerOutput output = new SwaggerOutput();  
17.         output.setId(input.getId());  
18.         output.setName("Swagger");  
19.         return output;  
20.     }  
21. }  

Web界面

启动项目，输入Http://Path/swagger-ui.html，就可以给前端展示相关的API文档，并像使用Postman以及Curl命令一样，通过Web界面进行接口测试。