Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版

本文主要是介绍Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

🧸欢迎来到dream_ready的博客,📜相信您对博主首页也很感兴趣o (ˉ▽ˉ;)

博主首页,更多redis、java等优质好文以及各种保姆级教程等您挖掘!

目录

一、介绍

二、导入依赖

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

四、设置静态资源映射

五、注意放开拦截器拦截 

六、使用方式

常用注解

标记数据 

Controller

Model 

七、查看演示效果

八、设置全局都穿的参数 —— 例如token


一、介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,就可以做到生成接口文档,以及在线接口调试页面。

官网:https://swagger.io/

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

二、导入依赖

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

此处导入的是Knife4j,这是一个为MVC框架集成Swagger生成文档的解决方案 

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

亲爱的朋友,希望你不要告诉我你不会写配置类,不会配置类的话看文末最下面有最基础的配置类的教程,保证你能用上最好用的Swagger文档

是在配置类中添加下面内容哦

注意修改里面的一些内容,比如汉字部分以及那个扫描包的路径

    /*** 通过knife4j生成接口文档* @return*/@Beanpublic Docket docket1() {log.info("准备生成接口文档...");ApiInfo apiInfo = new ApiInfoBuilder().title("皮肤肿瘤分类项目接口文档").version("2.0").description("皮肤肿瘤分类项目接口文档").build();Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("接口").apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("com.example.cvresume.controller")).paths(PathSelectors.any()).build();return docket;}

这个扫描包的路径切记要修改哦 

需要注意的是,这个方法可以设置多个,来使接口文档分页,只要方法名不重复即可

四、设置静态资源映射

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

也是在配置类中书写哦

下面这个基本是固定的,不用改,若你想玩一下Swagger的更多玩法,那么你可以去查阅官方文档

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

五、注意放开拦截器拦截 

要注意拦截器拦截,比如如果你设置的有JWT校验,那么就要在配置拦截器那里放开下面这几个静态资源

"/swagger-resources/**", "/doc.html", "/webjars/**", "/v2/**", "/swagger-ui.html/**"

类似我这样写:

六、使用方式

其实你已经可以使用了,来进入这个页面看一下吧

当你在写配置的时候,需要指定一个扫描路径,它就会自动扫描所有接口,获取对应的数据,构建接口文档

浏览器输入下面这个地址

注意修改ip和端口号为你正在使用的,其他不变

http://127.0.0.1:8080/doc.html

只不过你会发现它没有备注,当你遇到很麻烦的数据的时候,根本不知道每个属性是干嘛的,这时候就需要使用注解了 

利用注解标记Controller和Model层对应的数据,然后利用这些标记的数据自动生成接口文档中对应数据的备注 

常用注解

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

标记数据 

现在我对我的login接口进行改造,使其出现在接口文档上

我这里将原来和标记后的代码都进行了展示,主要是看注解,不要看我的逻辑代码,此篇博客只是为了让大家真正上手Swagger的使用

Controller

原来的:

标记后:

可以看到我用@Api标记了UserCroller这个类,用@ApiOperation标记了login这个方法

Model 

其实基本项目中的所有Model都要做标记,因为不一定啥时候用到,Model做标记的主要原因是让Swagger知道传来了什么参数(传对象时),或返回了什么参数

原来的:

@Data
public class User {private Integer id;private String username; // 用户名private String password; // 密码private String nickname; // 昵称private String avatarPath; // 头像路径private String sex; // 性别private String phone; // 电话private Integer role; // 角色private String hospital; // 医院名称private LocalDateTime createTime;private LocalDateTime updateTime;
}

标记后:

可以看到,我利用了@ApiModel标记实体类,用@ApiModelProperty标记属性

@Data
@ApiModel(description = "用户信息")
public class User {@ApiModelProperty(value = "用户ID")private Integer id;@ApiModelProperty(value = "用户名")private String username;@ApiModelProperty(value = "密码")private String password;@ApiModelProperty(value = "昵称")private String nickname;@ApiModelProperty(value = "头像路径")private String avatarPath;@ApiModelProperty(value = "性别")private String sex;@ApiModelProperty(value = "电话")private String phone;@ApiModelProperty(value = "角色")private Integer role;@ApiModelProperty(value = "医院名称")private String hospital;@ApiModelProperty(value = "创建时间")private LocalDateTime createTime;@ApiModelProperty(value = "更新时间")private LocalDateTime updateTime;
}

然后因为我这个项目有一个统一返回的对象Result,所以我对Result也要用注解加个标记

原来的:

标记后:

七、查看演示效果

咱们来发送个请求:

点击调试,可以看到,需要传的参数直接给我们了,多么的方便呀

当时,参数值需要我们填哈哈

来我们再看一个,哪怕传来的是对象,他也应对自如

点击调试,我们只需要填写参数值即可

若你想全部都加上备注,就需要辛苦一下啦

说一个小窍门,丢给GPT,然后修改一下即可哈哈哈

八、设置全局都穿传的参数 —— 例如token

例如我这里

手动先发送个请求,获取登陆后的token

将token添加到“全局参数设置”这里

点击添加参数

这个时候你再发送任何请求,都会自动带上这个全局参数了

教程至此结束,这篇教程更适用于新手,Swagger进阶等我有空了会补充,但这篇博客足以满足大部分学习者了

🧸前路漫漫,愿星光与您相伴!

这篇关于Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/916415

相关文章

JVM 的类初始化机制

前言 当你在 Java 程序中new对象时,有没有考虑过 JVM 是如何把静态的字节码(byte code)转化为运行时对象的呢,这个问题看似简单,但清楚的同学相信也不会太多,这篇文章首先介绍 JVM 类初始化的机制,然后给出几个易出错的实例来分析,帮助大家更好理解这个知识点。 JVM 将字节码转化为运行时对象分为三个阶段,分别是:loading 、Linking、initialization

Spring Security 基于表达式的权限控制

前言 spring security 3.0已经可以使用spring el表达式来控制授权,允许在表达式中使用复杂的布尔逻辑来控制访问的权限。 常见的表达式 Spring Security可用表达式对象的基类是SecurityExpressionRoot。 表达式描述hasRole([role])用户拥有制定的角色时返回true (Spring security默认会带有ROLE_前缀),去

浅析Spring Security认证过程

类图 为了方便理解Spring Security认证流程,特意画了如下的类图,包含相关的核心认证类 概述 核心验证器 AuthenticationManager 该对象提供了认证方法的入口,接收一个Authentiaton对象作为参数; public interface AuthenticationManager {Authentication authenticate(Authenti

Spring Security--Architecture Overview

1 核心组件 这一节主要介绍一些在Spring Security中常见且核心的Java类,它们之间的依赖,构建起了整个框架。想要理解整个架构,最起码得对这些类眼熟。 1.1 SecurityContextHolder SecurityContextHolder用于存储安全上下文(security context)的信息。当前操作的用户是谁,该用户是否已经被认证,他拥有哪些角色权限…这些都被保

Spring Security基于数据库验证流程详解

Spring Security 校验流程图 相关解释说明(认真看哦) AbstractAuthenticationProcessingFilter 抽象类 /*** 调用 #requiresAuthentication(HttpServletRequest, HttpServletResponse) 决定是否需要进行验证操作。* 如果需要验证,则会调用 #attemptAuthentica

Spring Security 从入门到进阶系列教程

Spring Security 入门系列 《保护 Web 应用的安全》 《Spring-Security-入门(一):登录与退出》 《Spring-Security-入门(二):基于数据库验证》 《Spring-Security-入门(三):密码加密》 《Spring-Security-入门(四):自定义-Filter》 《Spring-Security-入门(五):在 Sprin

Java架构师知识体认识

源码分析 常用设计模式 Proxy代理模式Factory工厂模式Singleton单例模式Delegate委派模式Strategy策略模式Prototype原型模式Template模板模式 Spring5 beans 接口实例化代理Bean操作 Context Ioc容器设计原理及高级特性Aop设计原理Factorybean与Beanfactory Transaction 声明式事物

Java进阶13讲__第12讲_1/2

多线程、线程池 1.  线程概念 1.1  什么是线程 1.2  线程的好处 2.   创建线程的三种方式 注意事项 2.1  继承Thread类 2.1.1 认识  2.1.2  编码实现  package cn.hdc.oop10.Thread;import org.slf4j.Logger;import org.slf4j.LoggerFactory

JAVA智听未来一站式有声阅读平台听书系统小程序源码

智听未来,一站式有声阅读平台听书系统 🌟&nbsp;开篇:遇见未来,从“智听”开始 在这个快节奏的时代,你是否渴望在忙碌的间隙,找到一片属于自己的宁静角落?是否梦想着能随时随地,沉浸在知识的海洋,或是故事的奇幻世界里?今天,就让我带你一起探索“智听未来”——这一站式有声阅读平台听书系统,它正悄悄改变着我们的阅读方式,让未来触手可及! 📚&nbsp;第一站:海量资源,应有尽有 走进“智听

活用c4d官方开发文档查询代码

当你问AI助手比如豆包,如何用python禁止掉xpresso标签时候,它会提示到 这时候要用到两个东西。https://developers.maxon.net/论坛搜索和开发文档 比如这里我就在官方找到正确的id描述 然后我就把参数标签换过来