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. @Configuration
9. @EnableWebMvc
10. @EnableSwagger2
11. @ComponentScan(basePackages ={"com.test.api"})
12. /**
13. *
14. * @author xiaozhou
15. */
16. public class SwaggerConfig {
17. /**
18. * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple
19. * swagger groups i.e. same code base multiple swagger resource listings.
20. */
21. @Bean
22. public Docket customDocket(){
23. return new Docket(DocumentationType.SWAGGER_2);
24. }
25. }

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. response.setHeader("Location",location);
19. }
20. @RequestMapping(value="/1.0/contact/update.do/{id}",method=RequestMethod.POST)
21. @ApiResponses(value = {
22. @ApiResponse(code = 200, message = "更新成功", response = Contact.class),
23. @ApiResponse(code = 404, message = "找不到页面"),
24. @ApiResponse(code = 500, message = "内部报错")}
25. )
26. public void update(@ApiParam(name="id", value="编号", required=true)@PathVariable Integer id,@RequestBody Contact contact) {
27. contact.setId(id);;
28. contactService.update(contact);
29. }
30. }

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/