SpringBoot 整合Swagger(生成API文档)

参考自蚂蚁课堂

• 链接：http://www.mayikt.com/

概述

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

传统的API文档编写存在以下几个痛点:

• 1.对API文档进行更新的时候，需要通知前端开发人员,导致文档更新交流不及时;API接口返回信息不明确缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUl等
• 2.接口文档太多，不便于管理
• 3.为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点：

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

pom引入依赖

        
        
            io.springfox
            springfox-swagger-ui
            3.0.0
        

        
            io.springfox
            springfox-swagger-ui
            3.0.0
        

        
            io.springfox
            springfox-swagger-common
            3.0.0
        

新建配置文件 SwaggerConfig

/**
 * @author 索悻流年
 * @title:接口文档配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //        RequestHandlerSelectors.any() 扫描所有
    //        RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 扫描带有ApiOperation注解
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build().host("testm.shennongjishi.cn");
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("会员服务")
                .description("个人练习项目")
                .version("1.0")
                .build();
    }
}

新建Server

@RestController
@RequestMapping("/user")
@Api(tags = "用户接口")
public class UserController {

    @ApiOperation("接口详细描述")
//    接口参数描述
    @ApiImplicitParam(name = "id", value = "用户id", required=true, dataType = "String")
//    生成post请求接口
    @PostMapping("/swaggerIndex")
    public String swaggerIndex(String id){
        return "测试swagger";
    }


    /**
     * 手机号登录
     * @param phoneNumber 手机号
     * @param passwork 密码
     * @return
     */
    @ApiOperation("手机号登录")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "phoneNumber",value = "手机号",required = true),
            @ApiImplicitParam(name = "passwork",value = "MD5 加密后的密码",required = true),
    })
    @PostMapping("/login")
    BaseResponse login(Spring phoneNumber,String passwork);

}

DTO生成

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author liuyan
 * @desc 获取设备列表DTO
 * @date 2021/3/1 14:01
 */
@Data
@ApiModel(description = "分页参数")
public class QueryDeviceListRequestDTO {
    /**
     * 页数
     */
    @ApiModelProperty(value = "页数", name = "page", example = "0")
    private Integer page;
    /**
     * 每页查询条数
     */
    @ApiModelProperty(value = "每页查询条数", name = "pageSize", example = "10")
    private Integer pageSize;
}

app启动类添加配置

@SpringBootApplication
@EnableSwagger2Doc
public class SystemApplication {
    public static void main(String[] args) {
        SpringApplication.run(SystemApplication.class, args);
        System.out.println("ヾ(◍°∇°◍)ﾉﾞ   启动成功      ヾ(◍°∇°◍)ﾉﾞ\n");
    }
}

启动springboot项目

浏览器访问