Swagger+Spring MVC框架学习分享

[html] view plain copy

1. 最近参与公司接口编写，Android和IOS端都要调用这些接口，需要对接调试，如果没有一个接口文档，管理接口，别人用了接口，也不知道接口怎么用，接口上有什么参数，哪些是必须参数，哪些是非必须参数，于是研究了Swagger框架应用到项目中去，Swagger与Spring项目结合，Spring必须是4.0以上版本，下面是研究的小小demo:  

1、引入Swagger的jar包，由于我的是Maven项目，所以在pom.xml中（注意Spring是4.0以上版本）

[html] view plain copy

1. <dependency>  
2.            <groupId>io.springfox</groupId>  
3.            <artifactId>springfox-swagger2</artifactId>  
4.            <version>2.0.2</version>  
5.        </dependency>  
6.       <dependency>  
7.           <groupId>com.fasterxml.jackson.core</groupId>  
8.           <artifactId>jackson-annotations</artifactId>  
9.           <version>2.4.4</version>  
10.       </dependency>  
11.       <dependency>  
12.           <groupId>com.fasterxml.jackson.core</groupId>  
13.           <artifactId>jackson-databind</artifactId>  
14.           <version>2.4.4</version>  
15.       </dependency>  
16.       <dependency>  
17.           <groupId>com.fasterxml.jackson.core</groupId>  
18.           <artifactId>jackson-core</artifactId>  
19.           <version>2.4.4</version>  
20.       </dependency>    

2、 新增Swagger配置代码

[java] view plain copy

1. package cn.;  

[java] view plain copy

1. import org.springframework.context.annotation.Bean;  
2. import org.springframework.context.annotation.Configuration;  
3. import org.springframework.context.annotation.ComponentScan;  
4. import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
5. import springfox.documentation.spi.DocumentationType;  
6. import springfox.documentation.spring.web.plugins.Docket;  
7. import springfox.documentation.swagger2.annotations.EnableSwagger2;  
8.   
9. @Configuration  
10. @EnableWebMvc  
11. @EnableSwagger2  
12. @ComponentScan(basePackages ={"com.test.api"})  
13. /** 
14.  * 
15.  * @author xiaozhou  
16.  */  
17. public class SwaggerConfig {  
18.   
19.    /** 
20.     * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple 
21.     * swagger groups i.e. same code base multiple swagger resource listings. 
22.     */  
23.    @Bean  
24.    public Docket customDocket(){  
25.       return new Docket(DocumentationType.SWAGGER_2);  
26.   
27.    }  
28.   
29. }  

3、修改 applicationContext.xml

[html] view plain copy

1. <bean class="cn.conf.SwaggerConfig"/>  

4、增加一个测试的ContactController

[java] view plain copy

1. @Api(value = "contacts-api", description = "有关于用户的CURD操作", position = 5)  
2. @Controller  
3. @RequestMapping("/contacts")  
4. public class ContactController {  
5.   @Autowired ContactService contactService;  
6.   @ResponseBody  
7.   @RequestMapping(value="/1.0/contact/get.do/{id}",method=RequestMethod.GET)  
8.   public Contact get(@PathVariable Long id) {  
9.     return contactService.find(id);  
10.   }  
11.   @ApiOperation(value = "创建用户", notes = "返回用户实体对象", response = Contact.class, position = 2)  
12.   @RequestMapping(value = "/1.0/contact/add.do", method=RequestMethod.POST)  
13.   public void add(@RequestBody Contact contact,HttpServletResponse response) {  
14.     contactService.create(contact);  
15.     String location = ServletUriComponentsBuilder.fromCurrentRequest()  
16.       .pathSegment("{id}").buildAndExpand(contact.getId())  
17.       .toUriString();  
18.    
19.     response.setHeader("Location",location);          
20.   }  
21.    
22.   @RequestMapping(value="/1.0/contact/update.do/{id}",method=RequestMethod.POST)  
23.   @ApiResponses(value = {  
24.             @ApiResponse(code = 200, message = "更新成功", response = Contact.class),  
25.             @ApiResponse(code = 404, message = "找不到页面"),  
26.             @ApiResponse(code = 500, message = "内部报错")}  
27.   )  
28.   public void update(@ApiParam(name="id", value="编号", required=true)@PathVariable Integer id,@RequestBody Contact contact) {  
29.     contact.setId(id);;  
30.     contactService.update(contact);  
31.   }  
32. }  

5、 添加Swagger UI配置

从网上下载SwaggerUI项目，将dist下所有内容拷贝到本地项目webapp下面如下图

6、修改index修改index.html

将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json修改为http://localhost:8080/v2/api-docs

7、启动项目，访问http://localhost:8080/v2/index.html即可看到如下所示页面：

参考资料：

https://raibledesigns.com/rd/entry/documenting_your_spring_api_with

  http://www.2cto.com/kf/201502/376959.html

  http://www.3pillarglobal.com/insights/restful-api-documentation-using-swagger-and-spring-mvc

      http://springfox.github.io/