SpringBoot基础教程(四)——与Swagger2的结合

我们在实际开发过程中经常会遇到一个问题，就是接口文档。有时候接口还没开发完但是接口文档需要先给出，因为其他方也可以根据接口文档先搞起来。但是有时候在开发过程中会发现当初定义的不是那么完善，就会更改。这个过程又涉及到一些沟通之类的比较繁琐的事情。有问题出现，就会有有心人出来帮忙解决。一个产品Swagger2应运而生。他可以在我们定义Controller时通过Swagger2注解的方式自动生成文档，只要服务起着，这个文档就能一直看到。当接口发生调整时，接口文档也能跟着调整，是一款非常好用的工具。
废话不多说，我们继续看pom

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

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


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

springfox-swagger2是swagger2的核心库，包括了一些注解及处理逻辑等。springfox-swagger-ui 是页面的展示。下面我们看看配置文件

package com.shuqi;

import io.swagger.annotations.Api;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket apiDocket() {
        ApiInfo apiInfo = new ApiInfoBuilder().title("title").description("description")
                .termsOfServiceUrl("").version("1.0")
                .contact(new Contact("name", "", "email")).build();
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any())
                .build();
    }
}

@EnableSwagger2表示激活此功能，实现是通过导入进来了Swagger2DocumentationConfiguration这个配置类@Import({Swagger2DocumentationConfiguration.class})
既然是个配置文件，Bean就少不了。ApiInfo是关于Api文件的基础描述，比如说标题，描述，版本号，联系人等基础信息。其中我想说的是
apis(RequestHandlerSelectors.withClassAnnotation(Api.class))他可以定制要展示的Controller中的文档，比如这里我定义的是类上加了Api这个注解，那么那些没有加这个注解的Controller就不会展示到页面上，所以留给我们的操作空间还是蛮大的。看一眼Controller是怎么定义的

package com.shuqi.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
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.RestController;

@RestController
@Api
public class HelloController {

    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    @ApiOperation(value = "hello", notes = "hello")
    public String hello(@ApiParam("姓名") @RequestParam String name,@ApiParam("年龄") @RequestParam Integer age) {
        return "我的名字叫" + name + ",年龄是" + age;
    }
}

可以看到我们再类上加了Api的注解。在方法上加了ApiOperation的注解，标示是一个Api 接口，ApiParam标示对接口参数的描述。
下面我们启动项目，看一下效果。启动后，输入http://localhost:8080/swagger-ui.html，看到下面的页面

image.png
他不仅可以作为接口文档，还可以测试功能
image.png

输入值后点击Try it out

image.png

使用起来相当方便，搞起来吧。

下节将的内容是：SpringBoot基础教程(五)——与本地缓存的结合

本节项目源码