前文：
在日常工作中，开发人员经常会遇到写接口文档的工作，一般都是word文档，带来书写麻烦、维护麻烦的问题，比如改了源代码忘了更新文档、解释不明确带来歧义、无法在线尝试等等。swagger就是为了解决这些问题而产生的。这是官方的例子，截图如下
swagger原理
后台：后端部分与java集成，后最终会产生一个json文件。
前台：前台部分就是html、css、js文件，js利用后台产生的json文件构造api；
前台配置：
去 https://github.com/swagger-api/swagger-ui 下载zip包，解压后，将dist文件夹下的所有内容copy到，java web project的webapp下，比如，
maven依赖：
<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>
后台配置：
途径一：
在spring的applicationcontext.xml文件中，添加配置
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
<!-- 对包中的所有类进行扫描，以完成Bean创建和自动依赖注入的功能 稍后会创建该包：webmvct.cmd -->
<context:component-scan base-package="webmvct.cmd"/>
解释：swagger会扫描 base-package包下的所有类，生成api文档
将docapi文件下的index.html文件，url改为本工程的路径，如下图，
截止到现在，最简单的swagger配置已经完成。访问 http://localhost:8080/hi/docapi/index.html 就可以看到效果。
途径二：如果想进一步的定制，比如只扫描某个包下的某些路径，那么就需要用到定制类，途径二是基于途径一在功能上的扩展，所以要想达到定制效果首先将途径一配置好。
创建swaggerspringconfig定制类，比如
@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包下的类也包含在内进行扫描；
customImplementation方法的includePatterns可以进行过滤，只include含有store的路径
controller类的样例：
@Api(value="/store",description="商店")
@Controller
@RequestMapping("/store")
public class StoreController {
@RequestMapping(value = "/{storeid}",method=RequestMethod.GET)
@ResponseBody
@ApiOperation(value="获取商店信息",notes="通过商店id获取商店信息")
public Store getStore(String storeid){
return new Store();
}
@ApiOperation(value="获取商店信息",notes="通过商店name获取商店信息")
@ResponseBody
@RequestMapping(value = "/{storename}",method=RequestMethod.POST)
public Store getStore2(String storeid){
return new Store();
}
}
@api，用在类上，用于解释整个类。
@apioperation，用于方法上，value是笼统的介绍方法作用，notes是详细的说明方法作用
最终效果图：
以上配置参考：
swagger整合spring mvc的doc 点击打开链接
swagger注解说明 点击打开链接
