当前位置： 首页 > article >正文

Swagger 教程(笔记) Knife4j

article 2025/1/18 13:14:17

假设获取到了整个项目，创建项目相应的结构

MySQL user 表

DROP DATABASE if EXISTS study;
CREATE DATABASE study;
USE study;
CREATE TABLE `users` (
	`id` INT(10) NOT NULL AUTO_INCREMENT,
	`username` VARCHAR(255) NOT NULL COLLATE 'utf8_general_ci',
	`password` VARCHAR(255) NOT NULL COLLATE 'utf8_general_ci',
	`create_time` DATETIME NOT NULL,
	`update_time` DATETIME NOT NULL,
	PRIMARY KEY (`id`) USING BTREE
)
COLLATE='utf8_general_ci'
ENGINE=InnoDB
;
INSERT INTO `users`(`username`,`password`,`create_time`,`update_time`) VALUES("Angindem","abc123456","2024-9-25 22:02:15","2024-9-25 22:02:15");

application.properties

# Mybatis 查找 *mapper.xml 路径
mybatis.mapper-locations=classpath:mappers/*xml
# MyBatis 为该包下的所有类自动注册别名。
mybatis.type-aliases-package=com.angindem.mybatis.po 

server.port=8080

# Mysql 数据库配置
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url= jdbc:mysql://localhost:3306/study
spring.datasource.username= root
spring.datasource.password= 123456

# 开启驼峰命名映射
mybatis.configuration.map-underscore-to-camel-case=true

# 打印 SQL 语句
mybatis.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

UserController

package com.angindem.controller;

import com.angindem.po.User;
import com.angindem.service.IUserService;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {

    private final IUserService userService;

    @GetMapping("/list")
    public List<User> getUserList(User user){
        return userService.getUserList(user);
    }

}

userMapper

package com.angindem.mapper;

import com.angindem.po.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;

import java.util.List;

@Mapper
public interface UserMapper {
    
    @Select("select * from users")
    List<User> queryByUser(User user);
}

User

package com.angindem.po;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    private Integer id;
    private String username;
    private String password;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
}

UserServiceImpl

package com.angindem.service.impl;

import com.angindem.mapper.UserMapper;
import com.angindem.po.User;
import com.angindem.service.IUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserServiceImpl implements IUserService {

    @Autowired
    private UserMapper userMapper;

    @Override
    public List<User> getUserList(User user) {
        return userMapper.queryByUser(user);
    }
}

IUserService

package com.angindem.service;

import com.angindem.po.User;

import java.util.List;


public interface IUserService {
    List<User> getUserList(User user);
}

Swagger教程

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接文档，以及在线接口调试页面。 官网:https://swagger.io/

对于使用Swagger插件，目前，一般都使用knife4j框架。如果直接使用官网 Swagger ，配置一些都是比较麻烦的。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。

Swagger前置配置

第一步：引入依赖，导入Maven坐标

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

第二步：webConfig配置类中加入 knife4j相关配置

 @Bean
    public Docket docket(){

        // API 接口文档主体信息的创建
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Angindem项目接口文档")    // 项目的标题
                .version("1.0")
                .contact(new Contact("Angindem","http://www.xx22x.com/","xxxxxxxx@qq.com")) // 添加作者个人信息
                .termsOfServiceUrl("http://www.xxx.com/")   // 服务的网址，公司或者个人的访问网址
                .description("这个项目可以使我们更加了解 Swagger ")  // 项目的描述
                .build();   // 注意 记得 build 创建

        // API 接口文档的 接口信息内容的创建
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)   // 放入主体信息
                .select()   // 选择功能
                .apis(RequestHandlerSelectors.basePackage("com.angindem.controller")) // 选择指定生成 API 接口需要扫描的包
                .paths(PathSelectors.any()) // Swagger 选择 扫描 所有的路径
                .build();   // 注意 记得 build 创建
        return docket;
    }

第三步：设置静态资源映射，否则接口文档页面无法访问

注意！！！ addResourceHandlers 这个方法名不可以随便写，
因为这个方法是继承 WebMvcConfigurationSupport 这个类的，进行了重写
package com.angindem.config;

import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

@Slf4j
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket docket(){

        // API 接口文档主体信息的创建
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Angindem项目接口文档")    // 项目的标题
                .version("1.0")
                .contact(new Contact("Angindem","http://www.xx22x.com/","xxxxxxxx@qq.com")) // 添加作者个人信息
                .termsOfServiceUrl("http://www.xxx.com/")   // 服务的网址，公司或者个人的访问网址
                .description("这个项目可以使我们更加了解 Swagger ")  // 项目的描述
                .build();   // 注意 记得 build 创建


        // API 接口文档的 接口信息内容的创建
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)   // 放入主题信息
                .select()   // 选择功能
                .apis(RequestHandlerSelectors.basePackage("com.angindem.controller")) // 选择指定生成 API 接口需要扫描的包
                .paths(PathSelectors.any()) // Swagger 选择 扫描 所有的路径
                .build();   // 注意 记得 build 创建
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
//    注意！！！ addResourceHandlers 这个方法名不可以随便写，因为这个方法是继承 WebMvcConfigurationSupport 这个类的，进行了重写
    protected void addResourceHandlers(ResourceHandlerRegistry registry){
        log.info("开始设置静态资源的映射");
//      将 Knife4j 的 Swagger-ui 静态资源放置在 classpath:/META-INF/resources/ 上，其中访问路径为 doc.html
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
//      将 Knife4j 生成的文档等其他资源 放置在  classpath:/META-INF/resources/webjars/** 上
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

尝试验证访问：localhost:8080/doc.html

访问通过，文档出现，配置成功！！！

Swagger 注解的使用

swagger常用注解

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

@ApiModel  跟  @ApiModelProperty   一起用

@Api   跟   @ApiOperation    一起用

@ApiModel  与  @ApiModelProperty 使用效果

User 类加入 Swagger 描述

package com.angindem.po;

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

import java.time.LocalDateTime;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "用户类")
public class User {

    @ApiModelProperty("用户ID")
    private Integer id;

    @ApiModelProperty("用户姓名")
    private String username;

    @ApiModelProperty("用户密码")
    private String password;

    @ApiModelProperty("用户创建时间")
    private LocalDateTime createTime;

    @ApiModelProperty("用户更新时间")
    private LocalDateTime updateTime;
}

使用前

使用后

@Api  与  @ApiOperation    使用效果

UserController 类加入 Swagger 描述

package com.angindem.controller;

import com.angindem.po.User;
import com.angindem.service.IUserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
@Api(tags = "用户相关api接口")
public class UserController {

    private final IUserService userService;

    @ApiOperation(value = "获取用户接口")
    @GetMapping("/list")
    public List<User> getUserList(User user){
        return userService.getUserList(user);
    }

}

使用前

使用后


http://www.kler.cn/a/319950.html

相关文章：

  • 在 Fluent 网格划分中使用薄网格特征
  • 利用EXCEL进行XXE攻击
  • c++ 中的容器 vector、deque 和 list 的区别
  • Ubuntu20.4和docker终端指令、安装Go环境、安装搜狗输入法、安装WPS2019：保姆级图文详解
  • Linux查看日志命令
  • 阀井可燃气体监测仪，开启地下管网安全新篇章-旭华智能
  • 怎么利用PHP发送彩信
  • layui如何获取当前地址栏的某个参数
  • String类常用的方法
  • linux命令之docker用法
  • uni-app安装插件
  • Rust 运算符快速了解
  • Uniapp时间戳转时间显示/时间格式
  • 每日OJ题_牛客_ 腐烂的苹果_多源BFS_C++_Java
  • 线性判别分析 (LDA)中目标函数两个相似公式 分子 之间的转换过程
  • AUTOSAR汽车电子嵌入式编程精讲300篇-基于CAN总线的气动控制（中）
  • 用 Django 5 快速生成一个简单 进销存 系统 添加 个打印 按钮
  • 10-pg内核之锁管理器（五）行锁
  • python划分CSV格式的数据集
  • 基于Jeecg-boot开发系统--后端篇
  • OpenHarmony（鸿蒙南向）——平台驱动开发【PIN】
  • Linux系统安装和配置 VNC 服务器
  • C语言 | Leetcode C语言题解之第423题从英文中重建数字
  • Trapezoidal Decomposition梯形分解算法（TCD）
  • 【Linux实践】实验四：Shell实用功能及文件权限
  • PHP API 框架：构建高效API的利器