Swagger 教程(笔记) Knife4j

news/2024/12/22 9:50:34/

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

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);}@GetMapping("/id")@ApiOperation(value = "获取用户接口",notes = "根据 id 和 用户名 参数查询用户")public List<User> getUserByIdOrUserName(Integer id,String name){return userService.getUserByIdOrUserName(id,name);}
}

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);@Select("select * from users where id = #{id} or username = #{name}")List<User> getUserByIdOrUserName(Integer id, String name);
}

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 {@Autowiredprivate UserMapper userMapper;@Overridepublic List<User> getUserList(User user) {return userMapper.queryByUser(user);}@Overridepublic List<User> getUserByIdOrUserName(Integer id, String name) {return userMapper.getUserByIdOrUserName(id,name);}
}

IUserService

package com.angindem.service;import com.angindem.po.User;import java.util.List;public interface IUserService {List<User> getUserList(User user);List<User> getUserByIdOrUserName(Integer id, String name);
}

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相关配置

 @Beanpublic 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 {@Beanpublic 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.htmlregistry.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的方法，说明方法的用途、作用
@ApiImplicitParams

用在方法上, 当方法有多个非封装的参数时，添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。

@ApiImplicitParam用在方法上，主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数

@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(value = "用户ID",required = false,example = "1")private Integer id;@ApiModelProperty(value = "用户姓名",required = true,example = "张三")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 = "获取用户接口",notes = "根据用户参数查询用户")@GetMapping("/list")public List<User> getUserList(User user){return userService.getUserList(user);}
}

使用前

使用后

@ApiImplicitParams注解  与  @ApiImplicitParam    使用效果

非类参数方法加入该注解

@GetMapping("/id")@ApiOperation(value = "根据条件获取用户接口",notes = "根据 id 和 用户名 参数查询用户")@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "用户id",required = false,example = "1"),@ApiImplicitParam(name = "name",value = "用户姓名",required = false,example = "李四")})public List<User> getUserByIdOrUserName(Integer id,String name){return userService.getUserByIdOrUserName(id,name);}

使用前

使用后


http://www.ppmy.cn/news/1532730.html

相关文章

manim中实现文字换行和设置字体格式

manim中实现文字换行和设置字体格式

实现换行 from manim import * class Textline(Scene): def construct(self): self.camera.background_color "#2F4F14" # 创建中心文本 horizontal_line Line(startLEFT * 8, endRIGHT * 8, colorWHITE).shift(3 * UP) stext Text("线性代数", …
阅读更多...
【C++打怪之路Lv4】-- 类和对象（中）

【C++打怪之路Lv4】-- 类和对象（中）

&#x1f308; 个人主页&#xff1a;白子寰 &#x1f525; 分类专栏&#xff1a;C打怪之路&#xff0c;python从入门到精通&#xff0c;数据结构&#xff0c;C语言&#xff0c;C语言题集&#x1f448; 希望得到您的订阅和支持~ &#x1f4a1; 坚持创作博文(平均质量分82)&#…
阅读更多...
X-Spreadsheet：Web端Excel电子表格工具库

X-Spreadsheet：Web端Excel电子表格工具库

在数字化时代&#xff0c;数据管理与分析的重要性日益凸显。传统的电子表格软件如Microsoft Excel和Google Sheets在数据处理方面发挥着重要作用&#xff0c;但在Web端&#xff0c;一款名为X-Spreadsheet的工具库正以其独特的优势逐渐崭露头角。本文将详细介绍X-Spreadsheet&am…
阅读更多...
C++的6种构造函数

C++的6种构造函数

在 C 中&#xff0c;构造函数是一种特殊的成员函数&#xff0c;用于初始化类对象。在对象创建时自动调用&#xff0c;构造函数的主要作用是分配资源、初始化数据成员等。根据不同的功能和使用场景&#xff0c;C 提供了多种类型的构造函数&#xff1a; 1. 默认构造函数 (Defaul…
阅读更多...
【C语言】字符和字符串函数(2)

【C语言】字符和字符串函数(2)

文章目录 一、strncpy函数的使用二、strncat函数的使用三、strncmp函数的使用四、strstr的使用和模拟实现五、strtok函数的使用六、strerr函数的使用 一、strncpy函数的使用 我们之前学习的strcpy的作用是把源字符串拷贝到目标空间内&#xff0c;而且经过我们的模拟实现&#x…
阅读更多...
大厂面试真题- RPC通讯协议如何保证数据完整性

大厂面试真题- RPC通讯协议如何保证数据完整性

RPC&#xff08;远程过程调用&#xff09;通讯协议保证数据完整性的方法主要依赖于多种技术手段和协议特性。以下是一些关键措施&#xff1a; 1. 加密技术 详细解释&#xff1a; 加密算法&#xff1a;加密算法如AES和RSA等&#xff0c;用于对RPC请求和响应数据进行加密。这些…
阅读更多...
建投数据自主研发相关系统获得欧拉操作系统及华为鲲鹏技术认证书

建投数据自主研发相关系统获得欧拉操作系统及华为鲲鹏技术认证书

近日&#xff0c;经欧拉生态创新中心和华为技术有限公司测评&#xff0c;建投数据自主研发的投资项目管理系统、全面风险管理信息系统、商业不动产业务系统&#xff0c;完成了基于欧拉操作系统openEuler 22.03、华为鲲鹏Kunpeng 920&#xff08;Taisha 200&#xff09;的兼容性…
阅读更多...
Redis 简单的消息队列

Redis 简单的消息队列

使用redis 进行简单的队列很容易&#xff0c;不需要使用较为复杂的MQ队列&#xff0c;直接使用redis 进行&#xff0c;不过唯一不足的需要自己构造生产者消费者&#xff0c;这里使用while True的方法进行消费者操作 目录 介绍数据类型StringHash 重要命令消息队列 介绍 key-v…
阅读更多...
最新文章

Copyright @ 2022~2023