SpringBoot 配置Swagger3.0接口文档

最新推荐文章于 2025-06-09 14:24:00 发布

成序猿@

最新推荐文章于 2025-06-09 14:24:00 发布

阅读量821

点赞数

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/m0_53273062/article/details/133886197

本文介绍了如何在SpringBoot项目中集成Swagger3.0.0，包括在pom.xml中添加依赖，创建SwaggerConfig配置类，指定接口路径，以及如何在控制器中使用@Api和@ApiModel注解来生成API文档。最后提供访问SwaggerUI的地址。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

1. Swagger配置类

第一步，需要在pom中引入相应的配置，这里使用的是3.0.0版本，SpringBoot使用的2.5.9 版本。

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
</dependency>

第二步

在代码中加入相应的配置，新建config包，写入SwaggerConfig配置类：

package com.cheng.springboot.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("标准接口")
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cheng.springboot.controller"))
                .paths(PathSelectors.any())
                .build();


    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("测试接口文档")
//                .description("认识接口文档")
//                .termsOfServiceUrl("...地址")
//                .contact(new Contact("cheng","htt","邮箱"))
                .version("1.0")
                .build();
    }

}

.apis(RequestHandlerSelectors.basePackage(“com.cheng.springboot.controller”))这个配置是用来指定我们的接口层的位置，大家可以根据你自己项目的实际情况来进行修改。.apiInfo()是定义一些我们项目的描述信息，可以根据实际需要在参数中修改。需要注意的是配置类的头部需要加上@Configuration。

2. 使用swagger

package com.cheng.springboot.controller;


import com.cheng.springboot.entity.User;
import com.cheng.springboot.mapper.UserMapper;
import com.cheng.springboot.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.AllArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@RestController
@AllArgsConstructor
@Api(value = "用户管理",tags = {"用户相关接口"})
@RequestMapping("/user")
public class UserController {

    private final UserMapper userMapper;
    private final UserService userService;

    @PostMapping("/insert")
    @ApiOperation(value = "添加用户")
    public boolean save(@RequestBody  User user){
        return  userService.saveUser(user);
    }

    @DeleteMapping("/delete/{id}")
    @ApiOperation(value = "删除用户")
    public Integer delete(@ApiParam(name="id",value="用户id",required=true) @PathVariable Integer id){
       return userMapper.deleteById(id);
    }

    // 分页查询
    // @RequestParam接收
    // limit第一个参数（pagenum-1）*pageSize

    @GetMapping("/page")
    @ApiOperation(value = "查询用户（分页）")
    public Map<String, Object> index(@ApiParam(name="pageNum",value="页码",required=true) @RequestParam Integer pageNum,@ApiParam(name="pageSize",value="每页几条",required=true) @RequestParam Integer pageSize){
        pageNum = (pageNum-1)*pageSize;
        Integer total = userMapper.selectTotal();
        Map<String, Object> res = new HashMap<>();
        List<User> data = userMapper.selectPage(pageNum, pageSize);
        res.put("data",data);
        res.put("total",total);
        return res;
    }
}

实体类中如何使用？

@ApiModel注解是用在接口相关的实体类上的注解，它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息，常常和@ApiModelProperty注解配合使用

@ApiModelProperty注解则是作用在接口相关实体类的属性（字段）上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，除了可以和 @ApiModel 注解关联使用，也会单独拿出来用。

作用域不同，@ApiModel作用在类上，@ApiModel作用来属性上

package com.cheng.springboot.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.fasterxml.jackson.annotation.JsonIgnore;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import lombok.Data;

@Data
@TableName(value = "user")
@ApiModel("userDTO")
public class User {
    @ApiModelProperty("用户id")
    @TableId(type = IdType.AUTO)
    private Integer id;
    @ApiModelProperty("用户名")

    private String username;
    @ApiModelProperty("密码")

    @JsonIgnore
    private String password;
    @ApiModelProperty("昵称")

    private String nickname;
    @ApiModelProperty("邮箱")

    private String email;
    @ApiModelProperty("手机号")

    private String phone;
    @TableField(value = "address")
    @ApiModelProperty("地址")

    private String address;

}

访问地址：http://localhost:9091/swagger-ui/index.html