微服务技术系列教程（26） - SpringCloud- 接口管理Swagger

引言

代码已提交到Github，有兴趣的同学可以看看：https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo

随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

提供的对象有： PC端、微信端、H5端、移动端（安卓和IOS端）

传统的API文档编写存在以下几个问题：

• 对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
• API接口返回信息不明确。
• 大公司中肯定会有专门文档服务器对接口文档进行更新。
• 缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
• 接口文档太多，不便于管理。

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

1. Swagger

Swagger Demo的代码已提交到Github，有兴趣的同学可以看看：https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo

Swagger具有以下优点：

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

1.1 Swagger集成步骤

1.新建Maven项目Swagger-Demo

2.添加Maven依赖

     org.springframework.boot
     spring-boot-starter-parent
     2.0.1.RELEASE
 

 
     
     
         org.springframework.boot
         spring-boot-starter-web
     
     
     
         io.springfox
         springfox-swagger2
         2.8.0
     
     
     
         io.springfox
         springfox-swagger-ui
         2.8.0
     
 

3.添加SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // api扫包
                .apis(RequestHandlerSelectors.basePackage("com.ylw.swagger.api")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("学生信息管理系统").description("对学生信息进行管理")
                .termsOfServiceUrl("http://www.xxx.com")
                // .contact(contact)
                .version("1.0").build();
    }

}

4.API注释

@RestController
@RequestMapping("api")
@Api("学生信息管理系统相关的api")
public class StudentController {

    private static final Logger logger = LoggerFactory.getLogger(StudentController.class);

    @ApiOperation(value = "新增学生信息", notes = "新增学生信息：用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"),
            @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"),
    })
    @RequestMapping(value = "/addStudent/{userName}/{sex}/{age}", method = RequestMethod.POST)
    public Response addStudent(@PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) {
        logger.info("新增学生信息操作");
        return new Response(200, "新增学生信息成功！");
    }


    @ApiOperation(value = "删除学生信息", notes = "删除学生信息：用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "uuid", value = "学生id", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/delStudent/{uuid}", method = RequestMethod.DELETE)
    public Response delStudent(@PathVariable String uuid) {
        logger.info("删除学生信息操作");
        return new Response(200, "删除学生信息成功！");
    }

    @ApiOperation(value = "修改学生信息", notes = "修改学生信息：用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"),
            @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"),
            @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"),
    })
    @RequestMapping(value = "/updateStudent/{id}/{userName}/{sex}/{age}", method = RequestMethod.POST)
    public Response updateStudent(@PathVariable String id, @PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) {
        logger.info("修改学生信息操作");
        return new Response(200, "修改学生信息成功！");
    }

    @ApiOperation(value = "查询学生信息", notes = "查询学生信息：用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/getStudent/{id}", method = RequestMethod.GET)
    public Response getStudent(@PathVariable String id) {
        logger.info("修改学生信息操作");
        return new Response(200, "修改学生信息成功！");
    }

}

5.浏览器访问

访问网址：http://localhost:8099/swagger-ui.html#/，可以看到接口文档自动生成了。 6.展开其中的一个接口 可以看到描述：