swagger

1、简介
项目使用springmvc+vue.js，最开始使用文档进行前后台的restApi的约定，后来发现接口太多，而且开发过程中必然要对接口进行变动。
Swagger可以充当前后端交流的重要桥梁，方便快捷，很实用。

2、集成

pom依赖

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

applicationContext.xml

<mvc:annotation-driven/>
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

需要创建一个swagger配置类

@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("com.controller")
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                                        .apiInfo(apiInfo())
                                        .includePatterns(".*?");
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                                "AAA RESTful API",
                                "AAA RESTful API 说明文档",
                                "服务目前接入终端有:Java client",
                                "aaa@qq.com",
                                "AAA",
                                "www.aaa.com"
                            );

        return apiInfo;
    }
}

controller代码的配置如下。
@Api表示一个表示一个开放的API，可以通过description简要描述该API的功能；
@ApiOperation表示对Api的操作，可以通过value，notes描述该操作的作用；

@Api(value = "数据源", description = "数据源相关api")
@Controller
@CrossOrigin(allowedHeaders="*", allowCredentials="true")
@RequestMapping("/aaa")
public class AAAController{

    @ApiOperation(value = "AAA题目", notes = "获取AAA实例")
    @RequestMapping(value = "/bbb/ccc", method = RequestMethod.GET)
    @ResponseBody
    public void getAAA(HttpServletResponse response) {
    }
}

某些post方法需要传body到后台，例如

@RequestMapping(value = "/aaa", method = RequestMethod.POST)
    @ResponseBody
    public void addAAA(HttpServletResponse response, @RequestBody CreateParam model) {
    ...

可以对model做标注

@ApiModel(value = "创建数据需要的参数")
public class CreateParam {
    @ApiModelProperty(value = "名字")
    private String name;

最终效果在
数据类型-》model中可以看到

集成Swagger-UI，从github上下载（https://github.com/wordnik/swagger-ui），并将dist目录下的内容拷贝到项目中webapp目录下即可。

修改index.html, 把Swagger UI对象中的URL替换为自己的API路径。

window.swaggerUi = new SwaggerUi({
        url: "/包名/api-doc",

最后访问“包名/api-doc/index.html”即可访问swagger主页，包含所有controller的各个方法