Swagger UI 快速入门-springmvc 整合Swagger UI 教程

现在很多开发团队都是前端开发与服务端分离，前端直接调用服务端写好接口。

如果你是服务端开发人员，也许你要做以下工作：

1、写接口文档，描述每个接口的功能，请求参数和返回结果

2、要自测自己所写的接口

解决上面两个问题，也许你之前的做法是

1、建一个wiki平台或文档，让前端自己去查看

2、使用单元测试或postman测试

有了Swagger UI ，会让你从中解放出来，在写代码的时候，就顺便把上面的事情给解决了

Swagger UI一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档

先来看下面几张效果图

是不是和postman有点像，是不是方法的描述、请求参数、返回值都有了。这都是怎么做到的？

官方第一手资料：

Swagger UI 官网： http://swagger.io/swagger-ui/

Swagger UI 源码地址： https://github.com/swagger-api/swagger-ui

由于项目中使用的是springmvc，所以只测试了Swagger UI结合springmvc的例子

先添加maven依赖，spring其他依赖在这里就不做多说

<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>

Swagger整合spring的配置类，此类会注入SpringSwaggerConfig，并配置Swagger拦截的路径、页面展示的信息等

package com._656463.swagger;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
 
@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan("com._656463.biz.*.controller")
public class ApiSwaggerConfig {
    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).apiInfo(apiInfo()).includePatterns(".*?");
    }
 
    private ApiInfo apiInfo(){
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title", //页面的标题
                "My Apps API Description",
                "My Apps API terms of service", 
                "My Apps API Contact Email", 
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

在spring配置文件中，声明这个bean，让其初始化（因为ApiSwaggerConfig我是放在一个特殊的包中，上线后直接去掉这个bean配置，让其不能被访问）

<bean class="com._656463.swagger.ApiSwaggerConfig" />

在controller中使用swagger ui

package com._656463.biz.web.controller.datatransfer;
 
import javax.annotation.Resource;
 
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
 
.......
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
 
@Controller
@RequestMapping("/datatransfer")
public class DataTransferController {
     
    @Resource
    private DataTransferFacade transferFacade;
     
    @ApiOperation(value = "根据订单ID同步数据", httpMethod = "GET", response = ResponseDto.class, notes = "syncByOrderId")
    @RequestMapping(value = "syncByOrderId", method = RequestMethod.GET)
    @ResponseBody
    public ResponseDto syncByOrderId(@ApiParam(required = true, name="orderId", value = "订单ID")  @RequestParam String orderId,Integer type) {
        。。。。。。
    }
}

@ApiOperation是配置该的一些信息，方便在页面展示，还有请求方式等

@ApiParam 是对参数的一些描述

在页面怎么展示呢，这是需要页面的，页面直接在Swagger UI 的github上下载最新的源码，然后把dist下面的所有文件拷贝到你的项目中，当然也可以放在其他能访问的web项目里。

https://github.com/swagger-api/swagger-ui/releases/tag/v2.2.5

例如我拷贝到我项目的webapp/docapi下

项目启动后，Swagger UI的访问地址是http://ip:host[/项目]/api-docs,所以把下载下来的url改为你项目的，然后请求回json数据让其前端代码解析

到此，就全部配置完毕

访问http://localhost:8067/docsapi/index.html就出现前面那个页面效果了