Java自动生成api文档
在 Java 开发中,自动生成 API 文档是一项非常实用的功能,它能帮助开发者快速了解项目中的类、方法、参数等信息。以下为你介绍几种常见的 Java 自动生成 API 文档的方式:
1. 使用 Javadoc
Javadoc 是 Java 自带的工具,它可以从 Java 源代码中的注释生成 API 文档。
代码注释规范
在 Java 代码中,使用特定格式的注释来描述类、方法、参数等信息。例如:
/*** 这是一个示例类,用于演示 Javadoc 的使用。** @author 开发者姓名* @version 1.0*/
public class ExampleClass {/*** 这是一个示例方法,用于计算两个整数的和。** @param a 第一个整数* @param b 第二个整数* @return 两个整数的和*/public int add(int a, int b) {return a + b;}
}
上述代码中,类注释使用 /** ... */ 包裹,包含了类的描述、作者和版本信息。方法注释同样使用 /** ... */ 包裹,包含了方法的描述、参数说明和返回值说明。
生成文档
在命令行中,进入包含 Java 源代码的目录,执行以下命令来生成 Javadoc 文档:
javadoc -d doc ExampleClass.java
其中,-d 选项指定生成文档的输出目录,doc 是输出目录的名称,ExampleClass.java 是要生成文档的 Java 源文件。如果有多个源文件,可以依次列出它们,或者使用通配符 *.java 表示当前目录下的所有 Java 文件。
查看文档
生成的文档会存放在指定的输出目录中,打开该目录下的 index.html 文件,就可以在浏览器中查看生成的 API 文档。
2. 使用 Swagger
Swagger 是一个强大的 API 文档生成工具,它可以自动生成 RESTful API 的文档,并且支持多种语言,包括 Java。
添加依赖
如果你使用 Maven 项目,在 pom.xml 中添加以下依赖:
<dependencies><!-- Swagger API 注解 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- Swagger UI --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
</dependencies>
配置 Swagger
创建一个配置类来启用 Swagger:
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build();}
}
上述代码中,@Configuration 注解表示这是一个配置类,@EnableSwagger2 注解启用 Swagger。Docket 是 Swagger 的核心配置类,通过 select() 方法选择要生成文档的控制器类和请求路径。
添加 API 注解
在控制器类和方法上添加 Swagger 注解来描述 API 信息:
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Api(value = "示例 API", description = "这是一个示例 API 文档")
public class ExampleController {@GetMapping("/hello")@ApiOperation(value = "获取问候语", notes = "返回一个简单的问候语")public String hello() {return "Hello, World!";}
}
上述代码中,@Api 注解用于描述控制器类的信息,@ApiOperation 注解用于描述方法的信息。
查看文档
启动 Spring Boot 应用程序后,访问 http://localhost:8080/swagger-ui.html(端口号根据实际情况修改),就可以在浏览器中查看生成的 API 文档。
3. 使用 Spring REST Docs
Spring REST Docs 是 Spring 官方提供的用于生成 RESTful API 文档的工具,它结合了测试用例来生成文档,确保文档的准确性。
添加依赖
如果你使用 Maven 项目,在 pom.xml 中添加以下依赖:
<dependencies><dependency><groupId>org.springframework.restdocs</groupId><artifactId>spring-restdocs-mockmvc</artifactId><version>2.0.6.RELEASE</version><scope>test</scope></dependency>
</dependencies>
编写测试用例并生成文档
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;@WebMvcTest(ExampleController.class)
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class ExampleControllerDocumentation {@Autowiredprivate MockMvc mockMvc;@Testpublic void shouldReturnDefaultMessage() throws Exception {this.mockMvc.perform(get("/api/hello")).andExpect(status().isOk()).andDo(document("hello",preprocessRequest(prettyPrint()),preprocessResponse(prettyPrint())));}
}
上述代码中,使用 @AutoConfigureRestDocs 注解自动配置 REST Docs,在测试用例中使用 document 方法生成文档片段。
集成文档
在 src/main/asciidoc 目录下创建 index.adoc 文件,将生成的文档片段集成到 AsciiDoc 文档中:
= 示例 API 文档== 问候语 APIinclude::{snippets}/hello/curl-request.adoc[]
include::{snippets}/hello/http-request.adoc[]
include::{snippets}/hello/http-response.adoc[]
生成 HTML 文档
使用 Asciidoctor 或其他工具将 AsciiDoc 文档转换为 HTML 文档:
asciidoctor -b html5 -a stylesheet=styles.css src/main/asciidoc/index.adoc -o target/generated-docs/index.html
通过以上几种方式,你可以根据项目的需求和特点选择合适的工具来自动生成 Java API 文档。
相关文章:
Java自动生成api文档
在 Java 开发中,自动生成 API 文档是一项非常实用的功能,它能帮助开发者快速了解项目中的类、方法、参数等信息。以下为你介绍几种常见的 Java 自动生成 API 文档的方式: 1. 使用 Javadoc Javadoc 是 Java 自带的工具,它可以从 J…...
PHP的JIT编译器
【图书介绍】《ThinkPHP 8高效构建Web应用》-CSDN博客 《2025新书 ThinkPHP 8高效构建Web应用 编程与应用开发丛书 夏磊 清华大学出版社教材书籍 9787302678236 ThinkPHP 8高效构建Web应用》【摘要 书评 试读】- 京东图书 PHP是一种广泛使用的脚本语言,被用于构建…...
Golang学习历程【第七篇 闭包type defer panic recover了解time包】
Golang学习历程【第七篇 闭包&type defer panic recover了解】 1. 闭包1.1 闭包的定义1.2 闭包的特点1.3 闭包的示例 2. 类型(type)2.1 自定义类型2.2 类型示例 3. 延迟执行(Defer)3.1 defer 的用法3.2 defer 示例 4. 恐慌(Panic…...
oracle表分区--范围分区
文章目录 oracle表分区分区的原因分区的优势oracle表分区的作用oracle表分区类型一、范围分区二、 创建分区表和使用:1、按照数值范围划分2、按照时间范围3、MAXVALUE2. 向现有表添加新的分区3、 分区维护和重新组织(合并/删除) oracle表分区…...
使用亚马逊针对 PyTorch 和 MinIO 的 S3 连接器进行模型检查点处理
2023 年 11 月,Amazon 宣布推出适用于 PyTorch 的 S3 连接器。适用于 PyTorch 的 Amazon S3 连接器提供了专为 S3 对象存储构建的 PyTorch 数据集基元(数据集和数据加载器)的实现。它支持用于随机数据访问模式的地图样式数据集和用于流式处理…...
Ubuntu 下 nginx-1.24.0 源码分析 - ngx_monotonic_time函数
声明 在 src\core\ngx_times.c 中: static ngx_msec_t ngx_monotonic_time(time_t sec, ngx_uint_t msec); 实现 在 src\core\ngx_times.c 中: static ngx_msec_t ngx_monotonic_time(time_t sec, ngx_uint_t msec) { #if (NGX_HAVE_CLOCK_MONOTONIC)st…...
业务开发 | 基础知识 | Maven 快速入门
Maven 快速入门 1.Maven 全面概述 Apache Maven 是一种软件项目管理和理解工具。基于项目对象模型的概念(POM),Maven 可以从中央信息中管理项目的构建,报告和文档。 2.Maven 基本功能 因此实际上 Maven 的基本功能就是作为 Ja…...
基于 Python(Flask)、JavaScript、HTML 和 CSS 实现前后端交互的详细开发过程
以下是一个基于 Python(Flask)、JavaScript、HTML 和 CSS 实现前后端交互的详细开发过程: --- ### 一、技术选型 1. **后端**:Python Flask(轻量级Web框架) 2. **前端**:HTML/CSS JavaScript&…...
STM32 RCC功能说明 复位和时钟控制RCC
目录 背景 RCC配置时钟主要涉及两方面 程序 第1步、RCC默认初始化 第2步、等待HSE工作稳定 第3步、设置PLL时钟源以及倍频数 第4步、设置AHB总线时钟(HCLK) 第5步、设置PCLK1(APB1总线) 第6步、设置PCLK2(APB2总线) 第7步、FLASH存储器的配置 …...
Windows可以永久暂停更新了
最终效果图: 第一步: winR组合键打开运行对话框,输入“regedit”,点击“确定”或回车: 第二步: 注册表定位到“\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsUpdate\UX\Settings”,新建DWO…...
高级 Python Web 开发:基于 FastAPI 构建高效实时聊天系统与并发控制
高级 Python Web 开发:基于 FastAPI 构建高效实时聊天系统与并发控制 目录 🌐 WebSocket 实时通讯概述💬 FastAPI 中实现 WebSocket 聊天系统🔧 WebSocket 并发控制与性能优化🔒 WebSocket 安全性与认证机制…...
深入理解Java虚拟机(JVM)
JVM概述 JVM作用 java虚拟机负责装载字节码到其内部,解释/编译为对应平台上的机器码指令执行,通俗说就是将字节码转换为机器码 JVM内部构造 1、类加载部分:负责把硬盘上的字节码加载到内存中(运行时数据区) 2、运…...
笔试面试——逻辑题
1.n从1开始,每个操作可以选择对n加1或者对n加倍,若想获得整数2014,最少需要多少个操作。 2.一个池塘,养龙虾若干,请想一个办法尽量准确的估算其中有多少龙虾? 3. S先生,P先生,Q先生他们知道桌子…...
【深度学习入门实战】基于Keras的手写数字识别实战(附完整可视化分析)
本人主页:机器学习司猫白 ok,话不多说,我们进入正题吧 项目概述 本案例使用经典的MNIST手写数字数据集,通过Keras构建全连接神经网络,实现0-9数字的分类识别。文章将包含: 关键概念图解完整实现代码训练过程可视化模型效果深度分析环境准备 import numpy as np impo…...
软考高级《系统架构设计师》知识点(一)
计算机硬件 校验码 码距:就单个编码A:00而言,其码距为1,因为其只需要改变一位就变成另一个编码。在两个编码中,从A码到B码转换所需要改变的位数称为码距,如A:00要转换为B:11,码距为2。一般来说,…...
用大模型学大模型01-制定学习计划
提示词:我想学习大模型,需要AI制定一个完整的学习计划,并给出学习路径和学习资料。以教科书目录的方式给出学习路线 第1章:数学与编程基础(4-6周) 1.1 数学基础 线性代数(矩阵运算、特征值分…...
lvs的DR模式
基于Linux的负载均衡集群软件 LVS 全称为Linux Virtual Server,是一款开源的四层(传输层)负载均衡软件 Nginx 支持四层和七层(应用层)负载均衡 HAProxy 和Nginx一样,也可同时支持四层和七层(应用层)负载均衡 基于Linux的高可用集群软件 Keepalived Keepalived是Linux…...
mysql读写分离与proxysql的结合
上一篇文章介绍了mysql如何设置成主从复制模式,而主从复制的目的,是为了读写分离。 读写分离,拿spring boot项目来说,可以有2种方式: 1)设置2个数据源,读和写分开使用 2)使用中间件…...
【C++学习篇】C++11第二期学习
目录 1. 可变参数模板 1.1 基本语法及原理 1.2 包扩展 1.3empalce系列接⼝ 2. lamba 2.1 lambda的语法表达式 2.2 捕捉列表 2.3 lamba的原理 1. 可变参数模板 1.1 基本语法及原理 1. C11⽀持可变参数模板,也就是说⽀持可变数量参数的函数模板和类模板&…...
TextWebSocketHandler 和 @ServerEndpoint 各自实现 WebSocket 服务器
TextWebSocketHandler 和 ServerEndpoint 都可以用于实现 WebSocket 服务器,但它们属于不同的技术栈,使用方式和功能有一些区别。以下是它们的对比: 1. 技术栈对比 特性TextWebSocketHandler (Spring)ServerEndpoint (Java EE/JSR-356)所属框…...
SCAU期末笔记 - 数据分析与数据挖掘题库解析
这门怎么题库答案不全啊日 来简单学一下子来 一、选择题(可多选) 将原始数据进行集成、变换、维度规约、数值规约是在以下哪个步骤的任务?(C) A. 频繁模式挖掘 B.分类和预测 C.数据预处理 D.数据流挖掘 A. 频繁模式挖掘:专注于发现数据中…...
使用分级同态加密防御梯度泄漏
抽象 联邦学习 (FL) 支持跨分布式客户端进行协作模型训练,而无需共享原始数据,这使其成为在互联和自动驾驶汽车 (CAV) 等领域保护隐私的机器学习的一种很有前途的方法。然而,最近的研究表明&…...
Linux-07 ubuntu 的 chrome 启动不了
文章目录 问题原因解决步骤一、卸载旧版chrome二、重新安装chorme三、启动不了,报错如下四、启动不了,解决如下 总结 问题原因 在应用中可以看到chrome,但是打不开(说明:原来的ubuntu系统出问题了,这个是备用的硬盘&a…...
ios苹果系统,js 滑动屏幕、锚定无效
现象:window.addEventListener监听touch无效,划不动屏幕,但是代码逻辑都有执行到。 scrollIntoView也无效。 原因:这是因为 iOS 的触摸事件处理机制和 touch-action: none 的设置有关。ios有太多得交互动作,从而会影响…...
Linux C语言网络编程详细入门教程:如何一步步实现TCP服务端与客户端通信
文章目录 Linux C语言网络编程详细入门教程:如何一步步实现TCP服务端与客户端通信前言一、网络通信基础概念二、服务端与客户端的完整流程图解三、每一步的详细讲解和代码示例1. 创建Socket(服务端和客户端都要)2. 绑定本地地址和端口&#x…...
R语言速释制剂QBD解决方案之三
本文是《Quality by Design for ANDAs: An Example for Immediate-Release Dosage Forms》第一个处方的R语言解决方案。 第一个处方研究评估原料药粒径分布、MCC/Lactose比例、崩解剂用量对制剂CQAs的影响。 第二处方研究用于理解颗粒外加硬脂酸镁和滑石粉对片剂质量和可生产…...
jmeter聚合报告中参数详解
sample、average、min、max、90%line、95%line,99%line、Error错误率、吞吐量Thoughput、KB/sec每秒传输的数据量 sample(样本数) 表示测试中发送的请求数量,即测试执行了多少次请求。 单位,以个或者次数表示。 示例:…...
STM32---外部32.768K晶振(LSE)无法起振问题
晶振是否起振主要就检查两个1、晶振与MCU是否兼容;2、晶振的负载电容是否匹配 目录 一、判断晶振与MCU是否兼容 二、判断负载电容是否匹配 1. 晶振负载电容(CL)与匹配电容(CL1、CL2)的关系 2. 如何选择 CL1 和 CL…...
【Linux系统】Linux环境变量:系统配置的隐形指挥官
。# Linux系列 文章目录 前言一、环境变量的概念二、常见的环境变量三、环境变量特点及其相关指令3.1 环境变量的全局性3.2、环境变量的生命周期 四、环境变量的组织方式五、C语言对环境变量的操作5.1 设置环境变量:setenv5.2 删除环境变量:unsetenv5.3 遍历所有环境…...
uniapp 集成腾讯云 IM 富媒体消息(地理位置/文件)
UniApp 集成腾讯云 IM 富媒体消息全攻略(地理位置/文件) 一、功能实现原理 腾讯云 IM 通过 消息扩展机制 支持富媒体类型,核心实现方式: 标准消息类型:直接使用 SDK 内置类型(文件、图片等)自…...
