swagger的使用与步骤

news2025/2/26 5:56:07

1、导入maven工程

首先我们创建一个 Spring Boot 项目，并引入 Swagger3 的核心依赖包，如下：

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

2、核心配置

接下来我们在启动类上添加两个注解，开启Swagger功能。

//开启swagger
@EnableSwagger2
@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

3、启动项目

接下来让我们可以启动项目，然后在浏览器中输入如下地址：

http://localhost:8085/swagger-ui/index.html

注意，端口是自己tomcat启动时的端口，以自己电脑的为准

4、进入界面

5、swagger配置类

package com.swagger.config;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("用户组")
            .select() .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.ant("/swagger/**"))
            .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
            .title("Api接口文档")
            .description("API描述")
            .version("1.0") .termsOfServiceUrl("https://www.baidu.com") .build(); }


}

6、Controller接口配置

@Api(tags = "用户控制")代表对这个controller的描述

@ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")代表对接口的描述

package com.swagger.controller;

import com.baomidou.mybatisplus.extension.api.R;
import com.swagger.domain.User;
import com.swagger.service.impl.UserServiceImpl;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Api(tags = "用户控制")
@RestController
@RequestMapping("/swagger/user")
@CrossOrigin
@Slf4j
public class UserController {
    @Autowired
    private UserServiceImpl userService;
    @GetMapping("/selectAll")
    @ResponseBody
    @ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")
    public R selectAll(){
        List<User> list = userService.list();
        System.out.println(list);
        return R.ok(list).setCode(200);
    }
    @PostMapping("/save")
    @ApiOperation(value = "新增用户", notes = "新增用户信息")
    public R save(@RequestBody User user){
        return R.ok("success").setCode(200);
    }

    @PutMapping("/update")
    @ApiOperation(value = "修改用户", notes = "修改用户信息")
    public R update(@RequestBody User user){
        return R.ok("success").setCode(200);
    }

    @DeleteMapping("/delete")
    @ApiOperation(value = "删除用户", notes = "删除用户信息")
    public R delete(int id){
        return R.ok("success").setCode(200);
    }

}

7、实体类配置

@ApiModel属性：description：用于描述实体类

@ApiModel(value = "用户实体",description = "用户实体")

@ApiModelProperty属性：notes：描述该实体类属性的信息

@ApiModelProperty(notes = "用户Id")

代码演示

package com.swagger.domain;

import com.baomidou.mybatisplus.annotation.*;

import java.io.Serializable;
import java.util.Date;

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

/**
 * 用户
 * @TableName pd_auth_user
 */
@TableName(value ="pd_auth_user")
@Data
@ApiModel(value = "用户实体",description = "用户实体")
public class User implements Serializable {
    /**
     * ID
     */
    @ApiModelProperty(notes = "用户Id")
    @TableId(value = "id")
    private Long id;

    /**
     * 账号
     */
    @ApiModelProperty(notes = "账号")
    @TableField(value = "account")
    private String account;

    /**
     * 姓名
     */
    @ApiModelProperty(notes = "姓名")
    @TableField(value = "name")
    private String name;

    /**
     * 组织ID
#c_core_org
     */
    @ApiModelProperty(notes = "组织ID")
    @TableField(value = "org_id")
    private Long org_id;

    /**
     * 岗位ID
#c_core_station
     */
    @ApiModelProperty(notes = "岗位ID")
    @TableField(value = "station_id")
    private Long station_id;

    /**
     * 邮箱
     */
    @ApiModelProperty(notes = "邮箱")
    @TableField(value = "email")
    private String email;

    /**
     * 手机
     */
    @ApiModelProperty(notes = "手机")
    @TableField(value = "mobile")
    private String mobile;

    /**
     * 性别
#Sex{W:女;M:男;N:未知}
     */
    @ApiModelProperty(notes = "性别   W:女;M:男;N:未知")
    @TableField(value = "sex")
    private String sex;

    /**
     * 启用状态 1启用 0禁用
     */
    @ApiModelProperty(notes = "启用状态 1启用 0禁用")
    @TableField(value = "status")
    private Boolean status;

    /**
     * 头像
     */
    @ApiModelProperty(notes = "头像")
    @TableField(value = "avatar")
    private String avatar;

    /**
     * 工作描述
比如：  市长、管理员、局长等等   用于登陆展示
     */
    @ApiModelProperty(notes = "工作描述\n" +
        "比如：  市长、管理员、局长等等   用于登陆展示")
    @TableField(value = "work_describe")
    private String work_describe;

    /**
     * 最后一次输错密码时间
     */
    @ApiModelProperty(notes = "最后一次输错密码时间")
    @TableField(value = "password_error_last_time")
    private Date password_error_last_time;

    /**
     * 密码错误次数
     */
    @ApiModelProperty(notes = "密码错误次数")
    @TableField(value = "password_error_num")
    private Integer password_error_num;

    /**
     * 密码过期时间
     */
    @ApiModelProperty(notes = "密码过期时间")
    @TableField(value = "password_expire_time")
    private Date password_expire_time;

    /**
     * 密码
     */
    @ApiModelProperty(notes = "密码")
    @TableField(value = "password")
    private String password;

    /**
     * 最后登录时间
     */
    @ApiModelProperty(notes = "最后登录时间")
    @TableField(value = "last_login_time")
    private Date last_login_time;

    /**
     * 创建人id
     */
    @ApiModelProperty(notes = "创建人id")
    @TableField(value = "create_user")
    private Long create_user;

    /**
     * 创建时间
     */
    @ApiModelProperty(notes = "创建时间")
    @TableField(value = "create_time",fill = FieldFill.INSERT)
    private Date create_time;

    /**
     * 更新人id
     */
    @ApiModelProperty(notes = "更新人id")
    @TableField(value = "update_user")
    private Long update_user;

    /**
     * 更新时间
     */
    @ApiModelProperty(notes = "更新时间")
    @TableField(value = "update_time",fill = FieldFill.INSERT_UPDATE)
    private Date update_time;

    @TableField(exist = false)
    private static final long serialVersionUID = 1L;
}

swagger显示