测试API框架 - Swagger介绍及Springboot集成

痛点

• 前后端编写接口文档的痛苦
• 编写及维护接口文档耗费不少精力，来不及更新
• 接口文档描述不正确

Swagger的作用

Swagger：https://swagger.io/
在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档

Springboot集成Swagger

1. maven依赖：pom.xml

作为Java服务端的大一统框架Spring，将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox

        <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>

2. 配置类：没有配置类Swagger无法运行

package demo.config;

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

/*
 * Author : zfk
 * Date : 14:46
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2
                .apiInfo(apiInfo()) // 用于定义api文档汇总信息,即下面的配置
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 指定controller类,即加了Api注解的类
                .paths(PathSelectors.any()) // 选择所有controller
                .build();
    }

    //构建api文档的相关信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 页面标题
                .title("JPATest API Doc")
                // 描述
                .description("This is a restful api document of nc server.")
                //版本号
                .version("1.0")
                .build();
    }
}

Docket是核心类，这里用流式编程，还有很多属性

其中.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 中指定controller为加了Api注解的类，其实RequestHandlerSelectors还有其他的配置

扫描包.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))

3. Controller配置

首先我们在Docket配置Controller是所有加上了@Api注解的类（也可以设置为扫描包）
接口上需要设置@ApiOperation注解

一个UserController：因为这里是讲Swagger，就不贴Springboot的mvc代码

package demo.controller;

import demo.entity.User;
import demo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

import java.util.Optional;

/**
 * Author : zfk
 * Date : 14:40
 */
@RestController
@Api("UserController")
public class UserController {

    @Autowired
    private UserService service;

    @GetMapping("/findById/{id}")
    @ApiOperation(value = "findById")
    public User findById(@PathVariable("id") String id){
        Optional<User> user = service.findById(id);
        return user.get();
    }


    @GetMapping("/finByName/{name}")
    @ApiOperation(value = "findByName")
    public User findByName(@PathVariable("name")String name){
        User user = service.findByName(name);

        return user;
    }

}

4. 运行Springboot后，访问地址http://localhost:8080/swagger-ui.html

界面：

5. 测试接口

一些常用注解

• Api：标记类，说明类的作用，可以标记一个Controller类做为swagger 文档资源

@Api(value = "UserController", description = "userController")

• ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• ApiModelProperty：描述一个model的属性

• ApiOperation：用在方法上，说明方法的作用

 @ApiOperation(value = "findById")

• ApiParam ： 请求属性

public User findById(@PathVariable("id") @ApiParam(value = "userId", required = true) String id){}

• ApiResponse ： 响应配置，放在方法上

• ApiResponses：响应集配置，可以设置多个@ApiResponse

---

knife4j强化Swagger

虽然Swagger很强，但有点丑，而且无法便捷导出接口文档，有需求就有市场，github就有对应的插件knife4j

knife4j完全遵循了springfox-swagger中的使用方式，并在此基础上做了增强功能

knife4j官方文档

快速开始

1. Maven导包（在Swagger的基础上，再导入knife4j包，版本）

        <!--整合Knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>

2. 在swagger的配置类上添加@EnableKnife4j

@EnableSwagger2
@Configuration
@EnableKnife4j
public class SwaggerConfig {
}

当然，需要更细节的配置

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.htphy.wx.module.dev.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

3. 启动Springboot，Knife4j网址为http://localhost:8080/doc.html

里面的下载功能很强大

还有很多优化的地方，具体看官方文档