Swagger的初步认识

前言

以前刚刚学Java的时候，写完接口和实现后，都没有测试的习惯，如果是前后端分离的项目，我们写后端服务的人把一个没有经过任何测试的接口给到前端，别人会非常抓狂。因为接口是前端和后端产生交互的地方，如果我们后端写完的接口有问题，而直接给别人，会很浪费时间。因此，后端每开发完一个接口，都非常有必要自己先测试，测试OK后再将接口文档提供给前端人员，最后进行前后端联调。需要一个非常快捷方便的工具来帮助后端进行接口测试，刚好接触到了Swagger，对它有了一个大概的了解。

1、Swagger是什么
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2、Swagger的作用

• 接口的文档在线自动生成。
• 接口功能的测试。

3、Swagger的基本使用

（1）pom依赖

		<!-- 引入swagger2依赖 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!-- swagger-ui依赖 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

（2）Swagger配置类

我这里将api单独作为一个工程独立出去了，所有的api都由这个工程管理。该工程的config包下有一个配置类，如下：

package com.ycz.api.config;

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;

/*
 * Swagger配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    //注册Docket
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                apis(RequestHandlerSelectors.basePackage("com.ycz")).
                paths(PathSelectors.any()).
                build();
    }
    
    //定义Api文档
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().
                title("个人信息api文档").
                description("个人信息api文档").
                version("1.0").
                build();
    }

}

（3）Api

package com.ycz.api.person;

import com.ycz.domain.others.QueryResponseResult;
import com.ycz.domain.others.ResponseResult;
import com.ycz.domain.person.Person;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Api(value = "个人信息管理",description = "提供个人的增删改查",tags = {"个人增删改查"})
public interface PersonControllerApi {
    
    @ApiOperation("按照地址查询个人信息")
    QueryResponseResult<Person> findPersonsByAddress(String address);
    
    @ApiOperation("添加记录")
    ResponseResult addPerson(Person person);
    
    @ApiOperation("修改记录")
    ResponseResult updatePerson(Person person);
    
    @ApiOperation("删除记录")
    ResponseResult delPerson(Integer id);
    
    @ApiOperation("分页查询")
    QueryResponseResult<Person> queryPersonsPaged(int page,int size);

}

（4）controller

我这里每个controller直接实现了api，接口在这里暴露出来，如下：

package com.ycz.swagger.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.ycz.api.person.PersonControllerApi;
import com.ycz.domain.others.QueryResponseResult;
import com.ycz.domain.others.ResponseResult;
import com.ycz.domain.person.Person;
import com.ycz.swagger.service.PersonService;

@RestController
@RequestMapping("/person")
public class PersonController implements PersonControllerApi{
    
    @Autowired
    PersonService personService;

    @Override
    @GetMapping("/list/{address}")
    public QueryResponseResult<Person> findPersonsByAddress(@PathVariable("address") String address) {
        return personService.findByAddress(address);
    }

    @Override
    @PostMapping("/savePerson")
    public ResponseResult addPerson(@RequestBody Person person) {
        return personService.addPerson(person);
    }

    @Override
    @PutMapping("/updatePerson")
    public ResponseResult updatePerson(@RequestBody Person person) {
        return personService.updatePerson(person);
    }

    @Override
    @DeleteMapping("/delPerson/{id}")
    public ResponseResult delPerson(@PathVariable("id") Integer id) {
        return personService.delPerson(id);
    }

    @Override
    @GetMapping("/list/{page}/{size}")
    public QueryResponseResult<Person> queryPersonsPaged(@PathVariable("page")int page, 
            @PathVariable("size")int size) {
        return personService.queryPersonsPaged(page,size);
    }

}

service和dao这里就不贴出来了，重点是研究Swagger。

（5）效果
启动springboot工程，我的接口是定的10000，启动工程后打开浏览器，
输入：http://localhost:10000/swagger-ui.html
注意是端口后直接加swagger-ui.html，固定格式。效果如下：

（6）测试
选择要进行测试的接口，这里我测一下查询，如下：

点击execute执行，返回结果如下：

返回类型是自定义的封装类型，这个接口的测试就OK了，没问题之后就可以导出形成文档交给前端人员了。