Spring Boot中结合Swagger2构建接口

一、简介

Swagger是全球最大的开源API规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。本篇只介绍如何在Spring boot项目中使用Swagger2，自动为API生成注释和规范API。

二、教程

1 创建maven项目，引进依赖

    <!---------spring boot依赖----------->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.2.RELEASE</version>
        <relativePath/> 
    </parent>

    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </dependency>

        <!----------swagge依赖----------->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

        <!----------lombok插件依赖----------->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.10</version>
        </dependency>
    </dependencies>

2 wagger2配置

@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config {
    @Bean
    public Docket createRestfulApi() {//api文档实例
        return new Docket(DocumentationType.SWAGGER_2)//文档类型：DocumentationType.SWAGGER_2
                .apiInfo(apiInfo())//api信息
                .select()//构建api选择器
                .apis(RequestHandlerSelectors.basePackage("com.yyh.controller"))//api选择器选择api的包
                .paths(PathSelectors.any())//api选择器选择包路径下任何api显示在文档中
                .build();//创建文档
    }

    private ApiInfo apiInfo() {//接口的相关信息
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful接口")
                .description("接口描述")
                .termsOfServiceUrl("termsOfServiceUrl")
                .contact("new Contact")
                .version("1.0")
                .license("http://springfox.github.io/springfox/docs/current/")
                .licenseUrl("http://springfox.github.io/springfox/docs/current/")
                .build();
    }

}

3 api相关注解的使用

@RestController//接口注解
@Api(value="用户接口",tags={"dogAPi"})//接口简要标注，对中文的支持不太好
@RequestMapping(value = "/swagger")//接口基本路径
public class AnimalController {
    //接口需要的参数，可以有多个，这里只写了一个，它的paramType还有path、query、body、form几种，
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
    //接口功能描述
    @ApiOperation(value = "获取一只狗")
    //接口响应信息，这里定义了一个401，当出现401，接口返回的是自定的错误AnimalError的实例。当然可以定义多个。
    @ApiResponses(value = { @ApiResponse(code = 401, message = "请求未通过认证.", response = AnimalError.class) })
    @RequestMapping(value="/onedog", method = RequestMethod.GET)
    public Dog oneDog(){
        return new Dog();
    }

    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
    @ApiOperation(value = "创建一只狗")
    @ApiResponses(value = { @ApiResponse(code = 401, message = "请求未通过认证.", response = AnimalError.class) })
    @RequestMapping(value="/dog/{name}", method = RequestMethod.GET)
    public Dog createDog(
            @ApiParam(defaultValue = "二哈")//@ApiParam和@RequestParam注解作用效果相同
            @PathVariable("name") String name){
        Dog dog = new Dog();
        dog.setName(name);
        return dog;
    }

4 查看效果
4.1 浏览器输入网址http://localhost:8080/swagger-ui.html#/

4.2 展开接口列表

4.3 下面我们进入第一个接口中

4.5 调用成功后

三、后续

此处只介绍了Spring boot中如何简单的使用swagger，详细学习还得看官方文档：http://springfox.github.io/springfox/docs/current/

源码：https://github.com/NapWells/java_framework_learn/tree/master/springswagger