Swagger2与Spring mvc集成

1. 介绍

 Swagger强大之处就在于他自动生成API文档，使后台开发不用频繁地写API文档。Swagger生成的api文档是实时更新的，你写的api接口有任何的改动都会在文档中及时的表现出来。看到这里是不是回想起之前手写的API文档那段日子，在现在看来确实很浪费时间。

2. maven依赖包

<!-- Swagger api文档生成工具依赖包 --><dependency>  <groupId>io.springfox</groupId>  <artifactId>springfox-swagger2</artifactId>  <version>2.2.2</version></dependency><dependency>  <groupId>com.fasterxml.jackson.core</groupId>  <artifactId>jackson-core</artifactId>  <version>2.2.3</version></dependency><dependency>  <groupId>com.fasterxml.jackson.core</groupId>  <artifactId>jackson-databind</artifactId>  <version>2.2.3</version></dependency><dependency>  <groupId>com.fasterxml.jackson.core</groupId>  <artifactId>jackson-annotations</artifactId>  <version>2.2.3</version></dependency><!-- Swagger end -->

3. 创建swagger的config类

/** * * @author Kris * @date 2017/12/05 */@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket myDocket() {        Docket docket = new Docket(DocumentationType.SWAGGER_2);        //API文档描述        ApiInfo apiInfo = new ApiInfo("API接口文档", "微信端API接口文档","1.0","apiDocs","","","");        docket.apiInfo(apiInfo);        // 下面这句代码是只生成被ApiOperation这个注解注解过的api接口        // 以及最后一定要执行build()方法,不然不起作用        docket.select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();        return docket;    }}

加载config的Bean

<!-- 注解驱动 --><mvc:annotation-driven /><!-- 扫描包 --><context:component-scan base-package="com.xxx"/><!--swagger的配置类--><bean class="com.xxx.swagger.SwaggerConfig" />

自定义类CustomSwaggerConfig这个类的bean定义放置在spring的哪个配置很重要,我这里定义的自动扫描包路径也是在这个配置文件中所以才将CustomSwaggerConfig放在这个类中.如果你的spring和springmvc分了两个配置文件,就要注意CustomSwaggerConfig的放置位置

4.API注解

** * @author shell */@Controller@Api(value = "controller的名字描述")@RequestMapping("/model")public class BaseModelController extends BaseController {    @Autowired    private BaseModelService service;    @RequestMapping("/test/{hhh}")    @ApiOperation(notes = "接口孟子", value = "test")    public ResultObject test(@ApiParam(required = true, name="參數名") @PathVariable("hhh") String hhh ) {        return resultObject;    }}

5、Swagger-Ui的设置

首先去官网下载Swagger-ui
链接地址：https://swagger.io/download-swagger-ui/
然后将dist下的文件夹拷贝到我们webapp下的swagger文件夹里
注意注意
将index.html文件中url设置
// 修改这个url地址为: http://{ip:port}/{projectname}/v2/api-docs
// {ip:port}: 改为你自己的项目地址, {projectname}:改为你自己的项目访问路径
// v2/api-docs: 固定不变
url = “http://localhost:8080/shiro/v2/api-docs“;

6、自定义Api接口页面

可以去下载swagger-editor
https://swagger.io/swagger-editor/

遇到的问题

问题1：访问时出现Failed to load spec，后来发现是index.html的url错误，没填写V2造成的

有问题可以留言。