当前位置: 首页 > news >正文

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 开发中&#xff0c;自动生成 API 文档是一项非常实用的功能&#xff0c;它能帮助开发者快速了解项目中的类、方法、参数等信息。以下为你介绍几种常见的 Java 自动生成 API 文档的方式&#xff1a; 1. 使用 Javadoc Javadoc 是 Java 自带的工具&#xff0c;它可以从 J…...

PHP的JIT编译器

【图书介绍】《ThinkPHP 8高效构建Web应用》-CSDN博客 《2025新书 ThinkPHP 8高效构建Web应用 编程与应用开发丛书 夏磊 清华大学出版社教材书籍 9787302678236 ThinkPHP 8高效构建Web应用》【摘要 书评 试读】- 京东图书 PHP是一种广泛使用的脚本语言&#xff0c;被用于构建…...

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. 延迟执行&#xff08;Defer&#xff09;3.1 defer 的用法3.2 defer 示例 4. 恐慌&#xff08;Panic&#xf…...

oracle表分区--范围分区

文章目录 oracle表分区分区的原因分区的优势oracle表分区的作用oracle表分区类型一、范围分区二、 创建分区表和使用&#xff1a;1、按照数值范围划分2、按照时间范围3、MAXVALUE2. 向现有表添加新的分区3、 分区维护和重新组织&#xff08;合并/删除&#xff09; oracle表分区…...

使用亚马逊针对 PyTorch 和 MinIO 的 S3 连接器进行模型检查点处理

2023 年 11 月&#xff0c;Amazon 宣布推出适用于 PyTorch 的 S3 连接器。适用于 PyTorch 的 Amazon S3 连接器提供了专为 S3 对象存储构建的 PyTorch 数据集基元&#xff08;数据集和数据加载器&#xff09;的实现。它支持用于随机数据访问模式的地图样式数据集和用于流式处理…...

Ubuntu 下 nginx-1.24.0 源码分析 - ngx_monotonic_time函数

声明 在 src\core\ngx_times.c 中&#xff1a; static ngx_msec_t ngx_monotonic_time(time_t sec, ngx_uint_t msec); 实现 在 src\core\ngx_times.c 中&#xff1a; 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 是一种软件项目管理和理解工具。基于项目对象模型的概念&#xff08;POM&#xff09;&#xff0c;Maven 可以从中央信息中管理项目的构建&#xff0c;报告和文档。 2.Maven 基本功能 因此实际上 Maven 的基本功能就是作为 Ja…...

基于 Python(Flask)、JavaScript、HTML 和 CSS 实现前后端交互的详细开发过程

以下是一个基于 Python&#xff08;Flask&#xff09;、JavaScript、HTML 和 CSS 实现前后端交互的详细开发过程&#xff1a; --- ### 一、技术选型 1. **后端**&#xff1a;Python Flask&#xff08;轻量级Web框架&#xff09; 2. **前端**&#xff1a;HTML/CSS JavaScript&…...

STM32 RCC功能说明 复位和时钟控制RCC

目录 背景 RCC配置时钟主要涉及两方面 程序 第1步、RCC默认初始化 第2步、等待HSE工作稳定 第3步、设置PLL时钟源以及倍频数 第4步、设置AHB总线时钟&#xff08;HCLK&#xff09; 第5步、设置PCLK1(APB1总线) 第6步、设置PCLK2(APB2总线) 第7步、FLASH存储器的配置 …...

Windows可以永久暂停更新了

最终效果图&#xff1a; 第一步&#xff1a; winR组合键打开运行对话框&#xff0c;输入“regedit”&#xff0c;点击“确定”或回车&#xff1a; 第二步&#xff1a; 注册表定位到“\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsUpdate\UX\Settings”&#xff0c;新建DWO…...

高级 Python Web 开发:基于 FastAPI 构建高效实时聊天系统与并发控制

高级 Python Web 开发&#xff1a;基于 FastAPI 构建高效实时聊天系统与并发控制 目录 &#x1f310; WebSocket 实时通讯概述&#x1f4ac; FastAPI 中实现 WebSocket 聊天系统&#x1f527; WebSocket 并发控制与性能优化&#x1f512; WebSocket 安全性与认证机制&#x1…...

深入理解Java虚拟机(JVM)

JVM概述 JVM作用 java虚拟机负责装载字节码到其内部&#xff0c;解释/编译为对应平台上的机器码指令执行&#xff0c;通俗说就是将字节码转换为机器码 JVM内部构造 1、类加载部分&#xff1a;负责把硬盘上的字节码加载到内存中&#xff08;运行时数据区&#xff09; 2、运…...

笔试面试——逻辑题

1.n从1开始&#xff0c;每个操作可以选择对n加1或者对n加倍&#xff0c;若想获得整数2014&#xff0c;最少需要多少个操作。 2.一个池塘&#xff0c;养龙虾若干&#xff0c;请想一个办法尽量准确的估算其中有多少龙虾? 3. S先生&#xff0c;P先生&#xff0c;Q先生他们知道桌子…...

【深度学习入门实战】基于Keras的手写数字识别实战(附完整可视化分析)

​ 本人主页:机器学习司猫白 ok,话不多说,我们进入正题吧 项目概述 本案例使用经典的MNIST手写数字数据集,通过Keras构建全连接神经网络,实现0-9数字的分类识别。文章将包含: 关键概念图解完整实现代码训练过程可视化模型效果深度分析环境准备 import numpy as np impo…...

软考高级《系统架构设计师》知识点(一)

计算机硬件 校验码 码距&#xff1a;就单个编码A:00而言&#xff0c;其码距为1&#xff0c;因为其只需要改变一位就变成另一个编码。在两个编码中&#xff0c;从A码到B码转换所需要改变的位数称为码距&#xff0c;如A:00要转换为B:11&#xff0c;码距为2。一般来说&#xff0c;…...

用大模型学大模型01-制定学习计划

提示词&#xff1a;我想学习大模型&#xff0c;需要AI制定一个完整的学习计划&#xff0c;并给出学习路径和学习资料。以教科书目录的方式给出学习路线 第1章&#xff1a;数学与编程基础&#xff08;4-6周&#xff09; 1.1 数学基础 线性代数&#xff08;矩阵运算、特征值分…...

lvs的DR模式

基于Linux的负载均衡集群软件 LVS 全称为Linux Virtual Server,是一款开源的四层(传输层)负载均衡软件 Nginx 支持四层和七层(应用层)负载均衡 HAProxy 和Nginx一样,也可同时支持四层和七层(应用层)负载均衡 基于Linux的高可用集群软件 Keepalived Keepalived是Linux…...

mysql读写分离与proxysql的结合

上一篇文章介绍了mysql如何设置成主从复制模式&#xff0c;而主从复制的目的&#xff0c;是为了读写分离。 读写分离&#xff0c;拿spring boot项目来说&#xff0c;可以有2种方式&#xff1a; 1&#xff09;设置2个数据源&#xff0c;读和写分开使用 2&#xff09;使用中间件…...

【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⽀持可变参数模板&#xff0c;也就是说⽀持可变数量参数的函数模板和类模板&…...

TextWebSocketHandler 和 @ServerEndpoint 各自实现 WebSocket 服务器

TextWebSocketHandler 和 ServerEndpoint 都可以用于实现 WebSocket 服务器&#xff0c;但它们属于不同的技术栈&#xff0c;使用方式和功能有一些区别。以下是它们的对比&#xff1a; 1. 技术栈对比 特性TextWebSocketHandler (Spring)ServerEndpoint (Java EE/JSR-356)所属框…...

突破不可导策略的训练难题:零阶优化与强化学习的深度嵌合

强化学习&#xff08;Reinforcement Learning, RL&#xff09;是工业领域智能控制的重要方法。它的基本原理是将最优控制问题建模为马尔可夫决策过程&#xff0c;然后使用强化学习的Actor-Critic机制&#xff08;中文译作“知行互动”机制&#xff09;&#xff0c;逐步迭代求解…...

练习(含atoi的模拟实现,自定义类型等练习)

一、结构体大小的计算及位段 &#xff08;结构体大小计算及位段 详解请看&#xff1a;自定义类型&#xff1a;结构体进阶-CSDN博客&#xff09; 1.在32位系统环境&#xff0c;编译选项为4字节对齐&#xff0c;那么sizeof(A)和sizeof(B)是多少&#xff1f; #pragma pack(4)st…...

YSYX学习记录(八)

C语言&#xff0c;练习0&#xff1a; 先创建一个文件夹&#xff0c;我用的是物理机&#xff1a; 安装build-essential 练习1&#xff1a; 我注释掉了 #include <stdio.h> 出现下面错误 在你的文本编辑器中打开ex1文件&#xff0c;随机修改或删除一部分&#xff0c;之后…...

Springcloud:Eureka 高可用集群搭建实战(服务注册与发现的底层原理与避坑指南)

引言&#xff1a;为什么 Eureka 依然是存量系统的核心&#xff1f; 尽管 Nacos 等新注册中心崛起&#xff0c;但金融、电力等保守行业仍有大量系统运行在 Eureka 上。理解其高可用设计与自我保护机制&#xff0c;是保障分布式系统稳定的必修课。本文将手把手带你搭建生产级 Eur…...

NLP学习路线图(二十三):长短期记忆网络(LSTM)

在自然语言处理(NLP)领域,我们时刻面临着处理序列数据的核心挑战。无论是理解句子的结构、分析文本的情感,还是实现语言的翻译,都需要模型能够捕捉词语之间依时序产生的复杂依赖关系。传统的神经网络结构在处理这种序列依赖时显得力不从心,而循环神经网络(RNN) 曾被视为…...

Caliper 配置文件解析:config.yaml

Caliper 是一个区块链性能基准测试工具,用于评估不同区块链平台的性能。下面我将详细解释你提供的 fisco-bcos.json 文件结构,并说明它与 config.yaml 文件的关系。 fisco-bcos.json 文件解析 这个文件是针对 FISCO-BCOS 区块链网络的 Caliper 配置文件,主要包含以下几个部…...

C#中的CLR属性、依赖属性与附加属性

CLR属性的主要特征 封装性&#xff1a; 隐藏字段的实现细节 提供对字段的受控访问 访问控制&#xff1a; 可单独设置get/set访问器的可见性 可创建只读或只写属性 计算属性&#xff1a; 可以在getter中执行计算逻辑 不需要直接对应一个字段 验证逻辑&#xff1a; 可以…...

Mysql8 忘记密码重置,以及问题解决

1.使用免密登录 找到配置MySQL文件&#xff0c;我的文件路径是/etc/mysql/my.cnf&#xff0c;有的人的是/etc/mysql/mysql.cnf 在里最后加入 skip-grant-tables重启MySQL服务 service mysql restartShutting down MySQL… SUCCESS! Starting MySQL… SUCCESS! 重启成功 2.登…...

GitHub 趋势日报 (2025年06月06日)

&#x1f4ca; 由 TrendForge 系统生成 | &#x1f310; https://trendforge.devlive.org/ &#x1f310; 本日报中的项目描述已自动翻译为中文 &#x1f4c8; 今日获星趋势图 今日获星趋势图 590 cognee 551 onlook 399 project-based-learning 348 build-your-own-x 320 ne…...

STM32标准库-ADC数模转换器

文章目录 一、ADC1.1简介1. 2逐次逼近型ADC1.3ADC框图1.4ADC基本结构1.4.1 信号 “上车点”&#xff1a;输入模块&#xff08;GPIO、温度、V_REFINT&#xff09;1.4.2 信号 “调度站”&#xff1a;多路开关1.4.3 信号 “加工厂”&#xff1a;ADC 转换器&#xff08;规则组 注入…...