在平時(shí)開(kāi)發(fā)寫(xiě)接口文檔的工作時(shí)，一般都是word文檔，帶來(lái)書(shū)寫(xiě)麻煩、維護(hù)麻煩的問(wèn)題，比如改了源代碼忘了更新文檔、解釋不明確帶來(lái)歧義、無(wú)法在線(xiàn)嘗試等等,swagger可以有效解決這類(lèi)問(wèn)題,需要的朋友可以參考下

前文：

在日常工作中，開(kāi)發(fā)人員經(jīng)常會(huì)遇到寫(xiě)接口文檔的工作，一般都是word文檔，帶來(lái)書(shū)寫(xiě)麻煩、維護(hù)麻煩的問(wèn)題，比如改了源代碼忘了更新文檔、解釋不明確帶來(lái)歧義、無(wú)法在線(xiàn)嘗試等等。swagger就是為了解決這些問(wèn)題而產(chǎn)生的。這是官方的例子，截圖如下

swagger原理

后臺(tái)：后端部分與java集成，后最終會(huì)產(chǎn)生一個(gè)json文件。

前臺(tái)：前臺(tái)部分就是html、css、js文件，js利用后臺(tái)產(chǎn)生的json文件構(gòu)造api；

前臺(tái)配置：

去https://github.com/swagger-api/swagger-ui 下載zip包，解壓后，將dist文件夾下的所有內(nèi)容copy到，java web project的webapp下，比如，

maven依賴(lài)：

<repositories>
    <repository>
      <id>jcenter-release</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-release-local/</url>
    </repository>
</repositories>
 
<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.1</version>
</dependency>

后臺(tái)配置：

途徑一：

在spring的applicationcontext.xml文件中，添加配置

 <mvc:annotation-driven/>
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
    <!-- 對(duì)包中的所有類(lèi)進(jìn)行掃描，以完成Bean創(chuàng)建和自動(dòng)依賴(lài)注入的功能 稍后會(huì)創(chuàng)建該包：webmvct.cmd -->    
	<context:component-scan base-package="webmvct.cmd"/>

解釋?zhuān)簊wagger會(huì)掃描 base-package包下的所有類(lèi)，生成api文檔

將docapi文件下的index.html文件，url改為本工程的路徑，如下圖，

截止到現(xiàn)在，最簡(jiǎn)單的swagger配置已經(jīng)完成。訪(fǎng)問(wèn) //localhost:8080/hi/docapi/index.html 就可以看到效果。

途徑二：

如果想進(jìn)一步的定制，比如只掃描某個(gè)包下的某些路徑，那么就需要用到定制類(lèi)，途徑二是基于途徑一在功能上的擴(kuò)展，所以要想達(dá)到定制效果首先將途徑一配置好。

創(chuàng)建swaggerspringconfig定制類(lèi)，比如

@Configuration
@EnableSwagger //Loads the spring beans required by the framework
@ComponentScan("com.test")
public class MySwaggerConfig {
	private SpringSwaggerConfig springSwaggerConfig;
 
	   /**
	    * Required to autowire SpringSwaggerConfig
	    */
	   @Autowired
	   public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
	      this.springSwaggerConfig = springSwaggerConfig;
	   }
 
	   /**
	    * Every SwaggerSpringMvcPlugin 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 SwaggerSpringMvcPlugin customImplementation(){
	      return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
	      .includePatterns(".*store.*");
	      
	   }
 
}

@componentscan，將com.test包下的類(lèi)也包含在內(nèi)進(jìn)行掃描；

customImplementation方法的includePatterns可以進(jìn)行過(guò)濾，只include含有store的路徑

controller類(lèi)的樣例：

@Api(value="/store",description="商店")
@Controller
@RequestMapping("/store")
public class StoreController {
	
	
	@RequestMapping(value = "/{storeid}",method=RequestMethod.GET)
	@ResponseBody
	@ApiOperation(value="獲取商店信息",notes="通過(guò)商店id獲取商店信息")
	public Store getStore(String storeid){
		return new Store();
	}
	
	@ApiOperation(value="獲取商店信息",notes="通過(guò)商店name獲取商店信息")
	@ResponseBody
	@RequestMapping(value = "/{storename}",method=RequestMethod.POST)
	public Store getStore2(String storeid){
		return new Store();
	}
}

@api，用在類(lèi)上，用于解釋整個(gè)類(lèi)。

@apioperation，用于方法上，value是籠統(tǒng)的介紹方法作用，notes是詳細(xì)的說(shuō)明方法作用

最終效果圖：