Swagger+Spring MVC框架学习分享

[html]
view plain
copy

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

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

[html]
view plain
copy

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.0.2</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>2.4.4</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>2.4.4</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>2.4.4</version>

</dependency>

2、新增Swagger配置代码

[java]
view plain
copy

package cn.;

[java]
view plain
copy

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.context.annotation.ComponentScan;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableWebMvc

@EnableSwagger2

@ComponentScan(basePackages ={"com.test.api"})

/**

*

* @author xiaozhou

*/

public class SwaggerConfig {

/**

* Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple

* swagger groups i.e. same code base multiple swagger resource listings.

*/

@Bean

public Docket customDocket(){

return new Docket(DocumentationType.SWAGGER_2);

}

}

3、修改applicationContext.xml

[html]
view plain
copy

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

4、增加一个测试的ContactController

[java]
view plain
copy

@Api(value = "contacts-api", description = "有关于用户的CURD操作", position = 5)

@Controller

@RequestMapping("/contacts")

public class ContactController {

@Autowired ContactService contactService;

@ResponseBody

@RequestMapping(value="/1.0/contact/get.do/{id}",method=RequestMethod.GET)

public Contact get(@PathVariable Long id) {

return contactService.find(id);

}

@ApiOperation(value = "创建用户", notes = "返回用户实体对象", response = Contact.class, position = 2)

@RequestMapping(value = "/1.0/contact/add.do", method=RequestMethod.POST)

public void add(@RequestBody Contact contact,HttpServletResponse response) {

contactService.create(contact);

String location = ServletUriComponentsBuilder.fromCurrentRequest()

.pathSegment("{id}").buildAndExpand(contact.getId())

.toUriString();

response.setHeader("Location",location);

}

@RequestMapping(value="/1.0/contact/update.do/{id}",method=RequestMethod.POST)

@ApiResponses(value = {

@ApiResponse(code = 200, message = "更新成功", response = Contact.class),

@ApiResponse(code = 404, message = "找不到页面"),

@ApiResponse(code = 500, message = "内部报错")}

)

public void update(@ApiParam(name="id", value="编号", required=true)@PathVariable Integer id,@RequestBody Contact contact) {

contact.setId(id);;

contactService.update(contact);

}

}

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/