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)所属框…...
微软PowerBI考试 PL300-选择 Power BI 模型框架【附练习数据】
微软PowerBI考试 PL300-选择 Power BI 模型框架 20 多年来,Microsoft 持续对企业商业智能 (BI) 进行大量投资。 Azure Analysis Services (AAS) 和 SQL Server Analysis Services (SSAS) 基于无数企业使用的成熟的 BI 数据建模技术。 同样的技术也是 Power BI 数据…...
【SpringBoot】100、SpringBoot中使用自定义注解+AOP实现参数自动解密
在实际项目中,用户注册、登录、修改密码等操作,都涉及到参数传输安全问题。所以我们需要在前端对账户、密码等敏感信息加密传输,在后端接收到数据后能自动解密。 1、引入依赖 <dependency><groupId>org.springframework.boot</groupId><artifactId...
【ROS】Nav2源码之nav2_behavior_tree-行为树节点列表
1、行为树节点分类 在 Nav2(Navigation2)的行为树框架中,行为树节点插件按照功能分为 Action(动作节点)、Condition(条件节点)、Control(控制节点) 和 Decorator(装饰节点) 四类。 1.1 动作节点 Action 执行具体的机器人操作或任务,直接与硬件、传感器或外部系统…...
P3 QT项目----记事本(3.8)
3.8 记事本项目总结 项目源码 1.main.cpp #include "widget.h" #include <QApplication> int main(int argc, char *argv[]) {QApplication a(argc, argv);Widget w;w.show();return a.exec(); } 2.widget.cpp #include "widget.h" #include &q…...
【android bluetooth 框架分析 04】【bt-framework 层详解 1】【BluetoothProperties介绍】
1. BluetoothProperties介绍 libsysprop/srcs/android/sysprop/BluetoothProperties.sysprop BluetoothProperties.sysprop 是 Android AOSP 中的一种 系统属性定义文件(System Property Definition File),用于声明和管理 Bluetooth 模块相…...
高危文件识别的常用算法:原理、应用与企业场景
高危文件识别的常用算法:原理、应用与企业场景 高危文件识别旨在检测可能导致安全威胁的文件,如包含恶意代码、敏感数据或欺诈内容的文档,在企业协同办公环境中(如Teams、Google Workspace)尤为重要。结合大模型技术&…...
04-初识css
一、css样式引入 1.1.内部样式 <div style"width: 100px;"></div>1.2.外部样式 1.2.1.外部样式1 <style>.aa {width: 100px;} </style> <div class"aa"></div>1.2.2.外部样式2 <!-- rel内表面引入的是style样…...
微信小程序云开发平台MySQL的连接方式
注:微信小程序云开发平台指的是腾讯云开发 先给结论:微信小程序云开发平台的MySQL,无法通过获取数据库连接信息的方式进行连接,连接只能通过云开发的SDK连接,具体要参考官方文档: 为什么? 因为…...
高防服务器能够抵御哪些网络攻击呢?
高防服务器作为一种有着高度防御能力的服务器,可以帮助网站应对分布式拒绝服务攻击,有效识别和清理一些恶意的网络流量,为用户提供安全且稳定的网络环境,那么,高防服务器一般都可以抵御哪些网络攻击呢?下面…...
CVE-2020-17519源码分析与漏洞复现(Flink 任意文件读取)
漏洞概览 漏洞名称:Apache Flink REST API 任意文件读取漏洞CVE编号:CVE-2020-17519CVSS评分:7.5影响版本:Apache Flink 1.11.0、1.11.1、1.11.2修复版本:≥ 1.11.3 或 ≥ 1.12.0漏洞类型:路径遍历&#x…...
