swagger简介

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。
浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息，包括附加的支持其他语言的库。

pom.xml(添加依赖)

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

swagger配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@Configuration
@EnableWebMvc
//需要扫描的接口包
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    // 一些接口文档信息的简介
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("spring Boot 中构建RESTful API")
                .termsOfServiceUrl("")
                .contact("caizi")
                .version("1.0")
                .build();
    }
}

swagger 注解用法

 1.对整个controller的描述注解
   @Api(value = "信息", description = "管理信息的API")
   2.对每一个接口的描述
    @ApiOperation(value = "修改信息", notes = "信息对象，信息标签，信息id")
   3.对每个参数进行描述
   @ApiParam(required = true, name = "postData"，value = "用户信息json数据") @RequestParam("tagData") String tagData

示例(在线测试时，需要注意参数的paramType参数的类型)

@Api(value = "CorpusController", description = "管理语料的方法")
public class CorpusController {
    @Autowired
    ICorpusService iCorpusService;

    @GETMapping(value = "/getCorpusByUserName")
    @ApiOperation(value = "getCorpusByUserName", notes = "获取语料")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "用户账号", required = true, dataType = "STRING",, paramType = "query"),
            @ApiImplicitParam(name = "corpusType", value = "语料分组类型", required = true, dataType = "STRING",, paramType = "query")
    })
    public String getCorpusByUserName(@RequestParam("userName") String userName,
                                      @RequestParam("corpusType") String corpusType) {
        String result = iCorpusService.getCorpusByUserName(userName, corpusType).toString();
        return result;
    }

}

使用

// 如果发布服务器可能路径还需要加上项目名
http://ip:port/swagger-ui.html

结语

当然这些公共的配置，都可以配置成spring-boot-starter这样方便后面的调用，同时也能更好的维护。

// swagger-spring-boot-starter 源码下载地址
github: https://github.com/zg091418/swagger2springbootstarter