简单使用Swagger

2024年 3月 24日 145.9k 0

1、介绍

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务(https://swagger.io/)。

它的主要作用是:

  • 使得前后端分离开发更加方便,有利于团队协作
  • 接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
  • 功能测试Spring 已经将 Swagger 纳入自身的标准,建立了 Spring-swagger 项目,现在叫 Springfox。通过在项目中引入 Springfox ,即可非常简单快捷的使用 Swagger。
  • knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案,前身是 swagger-bootstrap-ui,取名 kni4j 是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

    目前,一般都使用 knife4j 框架。

    2、 使用步骤

    1、导入 knife4j 的 maven 坐标

    在 pom.xml 中添加依赖

    <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
    </dependency>

    2、在配置类中加入 knife4j 相关配置

    WebMvcConfiguration.java

    /**
         * 通过knife4j生成接口文档
         * @return
    */
        @Bean
        public Docket docket() {
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("苍穹外卖项目接口文档")
                    .version("2.0")
                    .description("苍穹外卖项目接口文档")
                    .build();
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }

    3、设置静态资源映射,否则接口文档页面无法访问

    WebMvcConfiguration.java

    /**
         * 设置静态资源映射
         * @param registry
    */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    4、访问测试

    接口文档访问路径为 http://ip:port/doc.html —> http://localhost:8080/doc.html

    图片[1]-简单使用Swagger-不念博客

    接口测试:测试登录功能

    图片[2]-简单使用Swagger-不念博客

    思考:通过 Swagger 就可以生成接口文档,那么我们就不需要 Yapi 了?

    1、Yapi 是设计阶段使用的工具,管理和维护接口

    2、Swagger 在开发阶段使用的框架,帮助后端开发人员做后端的接口测试

    3、 常用注解

    通过注解可以控制生成的接口文档,使接口文档拥有更好的可读性,常用注解如下:

    注解 说明
    @Api 用在类上,例如 Controller,表示对类的说明
    @ApiModel 用在类上,例如 entity、DTO、VO
    @ApiModelProperty 用在属性上,描述属性信息
    @ApiOperation 用在方法上,例如 Controller 的方法,说明方法的用途、作用

    接下来,使用上述注解,生成可读性更好的接口文档

    在 sky-pojo 模块中

    EmployeeLoginDTO.java

    @Data
    @ApiModel(description = "员工登录时传递的数据模型")
    public class EmployeeLoginDTO implements Serializable {
    
        @ApiModelProperty("用户名")
        private String username;
    
        @ApiModelProperty("密码")
        private String password;
    
    }

    EmployeeLoginVo.java

    package com.sky.vo;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Builder;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    import java.io.Serializable;
    
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(description = "员工登录返回的数据格式")
    public class EmployeeLoginVO implements Serializable {
    
        @ApiModelProperty("主键值")
        private Long id;
    
        @ApiModelProperty("用户名")
        private String userName;
    
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("jwt令牌")
        private String token;
    
    }

    在 sky-server 模块中

    EmployeeController.java

    package com.sky.controller.admin;
    
    import com.sky.constant.JwtClaimsConstant;
    import com.sky.dto.EmployeeLoginDTO;
    import com.sky.entity.Employee;
    import com.sky.properties.JwtProperties;
    import com.sky.result.Result;
    import com.sky.service.EmployeeService;
    import com.sky.utils.JwtUtil;
    import com.sky.vo.EmployeeLoginVO;
    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.PostMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.HashMap;
    import java.util.Map;
    
    /**
     * 员工管理
     */
    @RestController
    @RequestMapping("/admin/employee")
    @Slf4j
    @Api(tags = "员工相关接口")
    public class EmployeeController {
    
        @Autowired
        private EmployeeService employeeService;
        @Autowired
        private JwtProperties jwtProperties;
    
        /**
         * 登录
         *
         * @param employeeLoginDTO
         * @return
         */
        @PostMapping("/login")
        @ApiOperation(value = "员工登录")
        public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO)  {
            //..............
    
    
        }
    
        /**
         * 退出
         *
         * @return
         */
        @PostMapping("/logout")
        @ApiOperation("员工退出")
        public Result<String> logout() {
            return Result.success();
        }
    
    }
    

    启动服务:访问http://localhost:8080/doc.html

    图片[3]-简单使用Swagger-不念博客

    相关文章

    JavaScript2024新功能:Object.groupBy、正则表达式v标志
    PHP trim 函数对多字节字符的使用和限制
    新函数 json_validate() 、randomizer 类扩展…20 个PHP 8.3 新特性全面解析
    使用HTMX为WordPress增效:如何在不使用复杂框架的情况下增强平台功能
    为React 19做准备:WordPress 6.6用户指南
    如何删除WordPress中的所有评论

    发布评论