Swagger 教程(笔记) Knife4j

Angindem

已于 2024-09-26 20:31:36 修改

阅读量855

点赞数 25

分类专栏：项目笔记文章标签：笔记

于 2024-09-26 00:43:00 首次发布

本文链接：https://blog.csdn.net/hacker_51/article/details/142533153

版权

项目笔记专栏收录该内容

3 篇文章 0 订阅

订阅专栏

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

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 {

    @Autowired
    private UserMapper userMapper;

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

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

 @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的方法，说明方法的用途、作用
@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);
    }