Swagger+Spring MVC框架學習分享

有些項目 Android和IOS端都要調用這些接口，需要對接調試，如果沒有一個接口文檔，管理接口，別人用了接口，也不知道接口怎麼用，接口上有什麼參數，哪些是必須參數，哪些是非必須參數，於是研究了Swagger框架應用到項目中去，Swagger與Spring項目結合，Spring必須是4.0以上版本.

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

<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配置代碼

package cn.;

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

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

4、增加一個測試的ContactController

@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://blog.csdn.net/zth1002/article/details/4692718