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)所属框…...
stm32G473的flash模式是单bank还是双bank?
今天突然有人stm32G473的flash模式是单bank还是双bank?由于时间太久,我真忘记了。搜搜发现,还真有人和我一样。见下面的链接:https://shequ.stmicroelectronics.cn/forum.php?modviewthread&tid644563 根据STM32G4系列参考手…...
golang循环变量捕获问题
在 Go 语言中,当在循环中启动协程(goroutine)时,如果在协程闭包中直接引用循环变量,可能会遇到一个常见的陷阱 - 循环变量捕获问题。让我详细解释一下: 问题背景 看这个代码片段: fo…...
转转集团旗下首家二手多品类循环仓店“超级转转”开业
6月9日,国内领先的循环经济企业转转集团旗下首家二手多品类循环仓店“超级转转”正式开业。 转转集团创始人兼CEO黄炜、转转循环时尚发起人朱珠、转转集团COO兼红布林CEO胡伟琨、王府井集团副总裁祝捷等出席了开业剪彩仪式。 据「TMT星球」了解,“超级…...
linux 错误码总结
1,错误码的概念与作用 在Linux系统中,错误码是系统调用或库函数在执行失败时返回的特定数值,用于指示具体的错误类型。这些错误码通过全局变量errno来存储和传递,errno由操作系统维护,保存最近一次发生的错误信息。值得注意的是,errno的值在每次系统调用或函数调用失败时…...
CocosCreator 之 JavaScript/TypeScript和Java的相互交互
引擎版本: 3.8.1 语言: JavaScript/TypeScript、C、Java 环境:Window 参考:Java原生反射机制 您好,我是鹤九日! 回顾 在上篇文章中:CocosCreator Android项目接入UnityAds 广告SDK。 我们简单讲…...
leetcodeSQL解题:3564. 季节性销售分析
leetcodeSQL解题:3564. 季节性销售分析 题目: 表:sales ---------------------- | Column Name | Type | ---------------------- | sale_id | int | | product_id | int | | sale_date | date | | quantity | int | | price | decimal | -…...
Spring数据访问模块设计
前面我们已经完成了IoC和web模块的设计,聪明的码友立马就知道了,该到数据访问模块了,要不就这俩玩个6啊,查库势在必行,至此,它来了。 一、核心设计理念 1、痛点在哪 应用离不开数据(数据库、No…...
有限自动机到正规文法转换器v1.0
1 项目简介 这是一个功能强大的有限自动机(Finite Automaton, FA)到正规文法(Regular Grammar)转换器,它配备了一个直观且完整的图形用户界面,使用户能够轻松地进行操作和观察。该程序基于编译原理中的经典…...
《C++ 模板》
目录 函数模板 类模板 非类型模板参数 模板特化 函数模板特化 类模板的特化 模板,就像一个模具,里面可以将不同类型的材料做成一个形状,其分为函数模板和类模板。 函数模板 函数模板可以简化函数重载的代码。格式:templa…...
根目录0xa0属性对应的Ntfs!_SCB中的FileObject是什么时候被建立的----NTFS源代码分析--重要
根目录0xa0属性对应的Ntfs!_SCB中的FileObject是什么时候被建立的 第一部分: 0: kd> g Breakpoint 9 hit Ntfs!ReadIndexBuffer: f7173886 55 push ebp 0: kd> kc # 00 Ntfs!ReadIndexBuffer 01 Ntfs!FindFirstIndexEntry 02 Ntfs!NtfsUpda…...
