10分钟Swagger2

SpringBoot整合Swagger

使用 Swagger 集成文档具有以下几个优势：

• 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
• 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
• 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

实现案例

1. 创建一个简单的SpringBoot项目

pom.xml

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
</dependency>

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

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

2. 基础Swagger配置文件

swaggerConfig.java

@Configuration
@EnableSwagger2
public class swaggerConfig {
     @Bean
    public Docket getClient() {
                return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).select().
                apis(RequestHandlerSelectors.any()).
                paths(PathSelectors.any()).
                build();
     }
     @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger 1102").version("1.0").build();
    }
}

3. 编写一个简单的Controller类

@Api(value = "DemoController")
@Controller
public class demoController {
    @ApiOperation(value = "DemoController  getHome",notes = "")
    @RequestMapping(value = "/",method = RequestMethod.GET)
    @ResponseBody
    public String getHome(){
        return "index";
    }
}

4. 打开浏览器输入

常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。

@Api: 修饰整个类，用于controller类上

@ApiOperation: 描述一个接口，用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时，描述对象的字段

@ApiResponse: Http响应其中的描述，在ApiResonse中

@ApiResponses: Http响应所有的描述，用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParam: 多个请求参数

进阶

在很多时候，我们需要在调用我们每一个接口的时候都携带上一些通用参数，比如采取token验证逻辑的往往在接口请求时需要把token也一起传入后台，接下来，我们就来讲解一下如何给Swagger添加固定的请求参数。

修改SwaggerConfig配置类，替换成如下内容，利用ParameterBuilder构成请求参数。

swaggerConfig.java

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        // 添加请求参数，我们这里把token作为请求头部参数传入后端
        ParameterBuilder parameterBuilder = new ParameterBuilder();  
        List<Parameter> parameters = new ArrayList<Parameter>();  
        parameterBuilder.name("token").description("令牌")
            .modelRef(new ModelRef("string")).parameterType("header").required(false).build();  
        parameters.add(parameterBuilder.build());  
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.any()).paths(PathSelectors.any())
                .build().globalOperationParameters(parameters);
//        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
//                .select()
//                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger API Doc")
                .description("This is a restful api document of Swagger.")
                .version("1.0")
                .build();
    }

}

再次测试Controller就会需要输入token了。