最近參與公司介面編寫，Android和IOS端都要呼叫這些介面，需要對接除錯，如果沒有一個介面文件，管理介面，別人用了介面，也不知道介面怎麼用，介面上有什麼引數，哪些是必須引數，哪些是非必須引數，於是研究了Swagger框架應用到專案中去，Swagger與Spring專案結合，Spring必須是4.0以上版本，下面是研究的小小demo:

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>  
 

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);

   }

}
 

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

@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);
  }
}
 

從網上下載SwaggerUI專案，將dist下所有內容拷貝到本地專案webapp下面如下圖

將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