SpringBoot整合Swagger2，形成接口文档

最新推荐文章于 2024-07-08 22:27:30 发布

原创最新推荐文章于 2024-07-08 22:27:30 发布 · 553 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#springboot #swagger2

springboot 同时被 2 个专栏收录

2 篇文章

订阅专栏

swagger2

1 篇文章

订阅专栏

本文详细介绍如何在SpringBoot项目中引入并配置Swagger2，包括依赖添加、配置代码示例及接口注解说明，帮助快速搭建RESTful API文档。

当然，首先是创建一个Spring Boot项目，加入web依赖，创建成功后，加入两个Swagger2相关的依赖，完整的依赖如下：

<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-web</artifactId>
</dependency>

Swagger2配置

Swagger2的配置也是比较容易的，在项目创建成功之后，只需要开发者自己提供一个Docket的Bean即可，如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .select()
                
                .apis(RequestHandlerSelectors.basePackage("cn.com.zz.flow.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("SpringBoot整合Swagger2 构建RESTful API")
                //条款地址
                .termsOfServiceUrl("http://despairyoke.github.io/")
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

如此，Swagger2就算配置成功了，非常方便。

此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：

创建接口

接下来就是创建接口了，Swagger2相关的注解其实并不多，而且很容易懂，下面我来分别向小伙伴们举例说明：

@RestController
@RequestMapping("/flow/user")
@Api(tags= "个人收藏夹接口")
public class BoxUserCollectController {

    @Autowired
    private BoxUserCollectService boxUserCollectService;

    @ApiOperation(value = "获取用户信息", notes = "获取用户信息")
    @RequestMapping(value = "/getUserAndMail", method = RequestMethod.POST)
    public APIResponse getUserAndMail(@RequestParam(name = "name", required = true) String name){
        if(name == null || "".equals(name)){
            return  APIResponse.fail("姓名必填");
        }
        List<BoxUserCollectEntity> list = boxUserCollectService.getUserMail(name);
        if(list != null && list.size() > 0){
            return  APIResponse.success(list);
        }
        return  APIResponse.success("没有查询到该用户信息");
    }
    @ApiOperation(value = "添加个人收藏用户", notes = "添加个人收藏用户")
    @RequestMapping(value = "/addUserList", method = RequestMethod.POST)
    public APIResponse addUserList(@RequestParam(name = "userCode", required = true) String userCode,
                                   @RequestBody @ApiParam(name="list",value="传入json格式",required=true) List<BoxUserCollectEntity> list){
        try {
            boxUserCollectService.add(list,userCode);
            return  APIResponse.success();
        }catch (Exception e){
            e.printStackTrace();
            return  APIResponse.fail("添加失败");
        }
    }
    @ApiOperation(value = "查询用户收藏", notes = "收藏用户名")
    @RequestMapping(value = "/getUserByCode", method = RequestMethod.POST)
    public APIResponse getUserByCode(@RequestParam(name = "userCode", required = true) String userCode){
        List<BoxUserCollectEntity> list = boxUserCollectService.getUserList(userCode);
        return APIResponse.success(list);
    }

这里边涉及到多个API，我来向小伙伴们分别说明：

@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@Data
@ApiModel("收藏用户类")
public class BoxUserCollectEntity extends Page implements Serializable {

    private static final long serialVersionUID = 1L;
    /**
     * id
     */
    @ApiModelProperty(value = "用户id")
    private String id;
    /**
     * 收藏用户名称
     */
    @ApiModelProperty(value = "收藏用户名")
    private String userCode;
    /**
     * 被收藏用户名称
     */
    @ApiModelProperty(value = "被收藏用户名", required = true)
    private String nameDisplay;
    /**
     * 被收藏地址
     */
    @ApiModelProperty(value = "被收藏邮箱地址", required = true)
    private String email;
    /**
     * 创建时间
     */
    @JsonFormat(timezone = "GMT+8",pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value = "创建时间")
    private Date createTime;

    /**
     * 状态 1 已存在 0 表示 删除
     */
    @ApiModelProperty(value = "状态")
    private String status;

}

测试接口：

返回接口：