swagger的使用与步骤

清疚 2023-10-09 21:41 47阅读 0赞

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、进入界面

![ab587241752a4b110b5d67f29ebebfe6.png][]

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的描述

![6b48f365192ff6f887e73e50ae7d98e9.png][]

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

![94c74de3f34d2417b431c1640d067eb2.png][]

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 = "用户实体")

![134b6274c3c85a1f0b1d0e6616e3f18a.png][]

@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显示

![0ebd05a9a129ad9aa90b76eea06b0d65.png][]

8、注解

![2ccc4cd08243e56955750a657c4f5401.png][]

[ab587241752a4b110b5d67f29ebebfe6.png]: https://img-blog.csdnimg.cn/img_convert/ab587241752a4b110b5d67f29ebebfe6.png
[6b48f365192ff6f887e73e50ae7d98e9.png]: https://img-blog.csdnimg.cn/img_convert/6b48f365192ff6f887e73e50ae7d98e9.png
[94c74de3f34d2417b431c1640d067eb2.png]: https://img-blog.csdnimg.cn/img_convert/94c74de3f34d2417b431c1640d067eb2.png
[134b6274c3c85a1f0b1d0e6616e3f18a.png]: https://img-blog.csdnimg.cn/img_convert/134b6274c3c85a1f0b1d0e6616e3f18a.png
[0ebd05a9a129ad9aa90b76eea06b0d65.png]: https://img-blog.csdnimg.cn/img_convert/0ebd05a9a129ad9aa90b76eea06b0d65.png
[2ccc4cd08243e56955750a657c4f5401.png]: https://img-blog.csdnimg.cn/img_convert/2ccc4cd08243e56955750a657c4f5401.png