smart-doc Java Restful API 文档生成工具

news2024/12/27 12:53:05

smart-doc简介

官方地址smart-doc

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释， smart-doc 就能帮你生成一个简易明了的 Markdown、Postman Collection2.0+、OpenAPI 3.0 + 的文档。除此之外 smart-doc 还支持生成漂亮简洁可调试的 html5 页面文档。

资讯来源开源中国

相信很多还在用swagger，但是swagger复杂的配置和入侵式代码增大了开发量。smart-doc相对对基于java标准注解的无入侵的在这方便完胜swagger。

smart-doc使用

smart-doc快速入门

  • 生成md文档

参考自smart-doc生成java 接口文档

导入依赖

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.1</version>
    <scope>test</scope>
</dependency>

严格模式下，会检测javadoc,如过没写注释会抛出异常

接口注释

/**
 * 评论控制器
 */
@RestController
@RequestMapping("/comment")
public class CommentController {


    /**
     * 添加评论
     * @return
     * @param comment  品论
     */
    @GetMapping("/add")
    void  addComment(Comment comment){
        System.out.println("添加评论");
    }

    /**
     * 删除评论
     * @param id  编号
     * @return
     */
    @GetMapping("/delete")
    void deleteComment(Integer id){
        System.out.println("删除评论");
    }

    /**
     * 删除评论
     * @param id  编号
     * @return
     */
    @GetMapping("/update")
    void updateComment(Integer id){
        System.out.println("编辑评论");
    }

    /**
     * 查询评论
     * @return
     */
    @GetMapping("/query")
    ResponseData queryComment(){
        Comment comment = new Comment();
        comment.setName("_小许_");
        comment.setAvatar("https://www.xiaoxu.com/picture/xiaoxu.jpg");
        comment.setType(1);
        comment.setCreateTime(new Date());
        List l = new ArrayList();
        l.add(comment);
        return ResponseData.SuccessRes(l);
    }
    
}

在控制器上至少有一个注释评论控制器，在url上也是至少有一个添加评论另外两个根据实际即可，注意没有参数不要写@param不然会报错。

参数和返回值注释

/**
 * 评论表
 *
 * @author admin
 * @date 2023/03/02
 */
@Data
public class Comment {
    /** 姓名 */
    private String name;
    /**
     * 头像
     */
    private String avatar;
    /**
     * 评论
     */
    private String comment;
    /**
     * 创建时间
     */
    private Date createTime;
    /**
     * 状态
     */
    private Integer type;

}

参数和返回值注释至少有/** 姓名 */注释，不然smart-doc生产文档的字段无注释。

配置启动类生产文档

 @Test
 public void testBuilderControllersApiSimple() {
     ApiConfig config = new ApiConfig();
     //服务地址
     config.setServerUrl("http://localhost:8010");
     //生成到一个文档
     config.setAllInOne(true);
     //采用严格模式
     config.isStrict();
     //文档输出路径
     config.setOutPath("src/main/resources/static/doc");
     ApiDocBuilder.builderControllersApi(config);
     //将生成的文档输出到src/main/resources/static/doc目录下，严格模式下api-doc会检测Controller的接口注释
 }

服务器地址是生产文档的示例地址，在导入postman，apifox等工具时有用，本地参考随意设计即可；设置严格模式smart-doc会严格检查注释，文档输出路径可以是相对路径也可以是绝对路径，但一般用相对路径./(默认为根项目路径)。上面配置生成类需要再spring环境中执行，直接在单元测试类配置即可。

如下图所示生成了一个AllInOne.md的文件：

在这里插入图片描述
在这里插入图片描述
生成了md的api文档，全程只引入了一个依赖，配置了一个生成器就完成了api接口的生成而且界面简精简，是不是非常方便。

md已经生成到了templates，通过流的处理也可以在线文档观看，smart-doc也提供了maven和gradle的插件功能，用于生成文档，html和导入到postman工具。

  • 生成html文档

导入依赖

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>1.0.3</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>API文档</projectName>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

resources目录下新增smart-doc.json配置文件文件

{
  "serverUrl": "http://127.0.0.1:8080/api-demo/", //设置服务器地址,非必须
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "outPath": "src/main/resources/static/doc", //指定文档的输出路径
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "projectName": "CMP基础服务API文档",//配置自己的项目名称
  "showAuthor":true, //是否显示接口作者名称，默认是true,不想显示可关闭
  "dataDictionaries": [ //配置数据字典，没有需求可以不设置
    {
      "title": "状态字典",
      "enumClassName": "cn.xx.docStatusEnum",
      "codeField": "key",
      "descField": "value"
    }
  ]
}

maven运行,将会扫描controller生成文档,文档地址在上面定义的outPath参数

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman

在这里插入图片描述

tag名称描述
@ignoreignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看忽略响应字段，如果ignore加到方法上，则接口方法不会输出到文档。
@required如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。
@mock从smart-doc 1.8.0开始，mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档

springboot项目使用smart-doc生成api html文档

smart-doc官方文档

smart标签用法

在这里插入图片描述
生成了html和css，打开后如下所示：

在这里插入图片描述
在文档中，Required 和Since都是默认值，通过smart-doc的标签来更改：

在这里插入图片描述

@ignore忽略标签用于筛选请求参数对象上的某个字段。@required设置某字段为必填或非必填

smart-doc 使用说明

由于生成的是html文件所以可以随服务一同部署，如下生成html文件

在这里插入图片描述
配置文件释放静态资源

spring.mvc.static-path-pattern=/static/**

spring视图解析器都是从resource下开始找相关文件的，因此插件生成的css是无法自动找到的，所以需要重新配置：

在这里插入图片描述

编写资源控制器：

@Controller
public class DocController {
    @GetMapping("/doc")
    public String getDoc(){
        return "static/doc/index.html";
    }
}

在这里插入图片描述
由于smart-doc是对源码的解析，所以每次改动源码都需要重新编译。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/384083.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

vue基础学习笔记

vue基础学习笔记

1.v-text 设置标签的文本值&#xff0c;将标签内的内容完全替换为v-text绑定的值。 如果想要保留标签内的值&#xff0c;可以采用差值表达式的方式&#xff08;<h2>text{{message}}</h2>&#xff09; 内部值支持拼接 <!DOCTYPE html> <html lang"en…
阅读更多...
Unity Asset Bundle学习 - 加载网络资源

Unity Asset Bundle学习 - 加载网络资源

昨天调试了一下加载本地资源 Unity Asset Bundle学习 - 加载本地资源 今天试一下用Asset Bundle加载网络数据 接着按照文档走 发现 有问题 引用命名空间一直报错 按文档走不通 就直接百度查了 查了好多 这个东西有很多前辈的经验 直接拷贝代码拿过来用的 下面这段是测试没问题…
阅读更多...
技术分享 | OceanBase 集群扩容缩容

技术分享 | OceanBase 集群扩容缩容

作者&#xff1a;杨文 DBA&#xff0c;负责客户项目的需求与维护&#xff0c;会点数据库&#xff0c;不限于MySQL、Redis、Cassandra、GreenPlum、ClickHouse、Elastic、TDSQL等等。 本文来源&#xff1a;原创投稿 *爱可生开源社区出品&#xff0c;原创内容未经授权不得随意使用…
阅读更多...
面试官：为什么说ArrayList线程不安全？

面试官：为什么说ArrayList线程不安全？

本博客知识点收录于&#xff1a;⭐️《JavaSE系列教程》⭐️ 1&#xff09;线程安全与不安全集合 我们学习集合的时候发现集合存在由线程安全集合和线程不安全集合&#xff1b;线程安全效率低&#xff0c;安全性高&#xff1b;反之&#xff0c;线程不安全效率高&#xff0c;安…
阅读更多...
Yuga Labs发布“TwelveFold“进军BTC，新大陆的探索即将开启

Yuga Labs发布“TwelveFold“进军BTC，新大陆的探索即将开启

Yuga Labs 正在将新的 NFT 引入比特币区块链&#xff0c;并于 2 月 28 日推出了一个名为 TwelveFold 的系列。该系列是比特币网络上“刻在 satoshis 上”的 300 个生成作品的限量版。据官方说明&#xff0c;TwelveFold将限量发行三百幅的生成式NFT 画作&#xff0c;每件NFT 作品…
阅读更多...
AcWing3696. 构造有向无环图

AcWing3696. 构造有向无环图

先看题&#xff1a; 首先来看一下题目的要求&#xff1a;利用给定的边来构造一个有向无环图。 那么什么是有向无环图呢&#xff1f;我们来搜索一番&#xff1a;"所谓有向无环图其实就是&#xff1a;有方向的边&#xff1b;这些边在一个图中不会构成一个闭合的环路。"…
阅读更多...
学习大数据应该掌握哪些技能

学习大数据应该掌握哪些技能

想要了解大数据开发需要掌握哪些技术&#xff0c;不妨先一起来了解一下大数据开发到底是做什么的~ 1、什么是大数据&#xff1f; 关于大数据的解释&#xff0c;比较官方的定义是指无法在一定时间范围内用常规软件工具进行捕捉、管理和处理的数据集合&#xff0c;是需要新处理模…
阅读更多...
C++STL详解（四）—— vector模拟实现

C++STL详解（四）—— vector模拟实现

文章目录vector内置成员变量默认成员函数初始化列表构造迭代器区间构造函数赋个数赋值构造函数赋值构造的相关问题拷贝构造函数赋值运算符重载函数析构函数迭代器及迭代器相关函数begin和end范围for容量与扩容相关函数size和capacityreserveresizeemptyvector中的增删查改&…
阅读更多...
「攻略手册」：ShardingSphere 与 Java 应用性能优化

「攻略手册」：ShardingSphere 与 Java 应用性能优化

笔者曾经写过一篇文章&#xff0c;介绍 ShardingSphere 在具体代码细节上的优化案例&#xff0c;但文章中没有介绍如何发现代码优化点。本文将结合之前笔者在 ShardingSphere 相关性能问题排查、优化经验&#xff0c;简要地介绍 ShardingSphere 性能问题排查、优化应如何入手。…
阅读更多...
解决Sql WorkBench中数据库不能重命名的问题

解决Sql WorkBench中数据库不能重命名的问题

解决Sql WorkBench中数据库不能重命名的问题mysql不支持直接重命名数据库1. 连接到数据库2. 打开菜单&#xff0c;选择迁移向导3. 点击Start Migration4. 填写源数据库的相应参数5. 填写目标数据库的响应参数6. 稍等片刻&#xff0c;点击Next7. 选择你要迁移的数据库。8. 进入一…
阅读更多...
B站依然面临巨大风险，盈利之路可能会更加艰难

B站依然面临巨大风险，盈利之路可能会更加艰难

来源&#xff1a;猛兽财经 作者&#xff1a;猛兽财经 哔哩哔哩(BILI)虽然得到了阿里巴巴(BABA)和腾讯(00700)的支持&#xff0c;在扩大和多样化用户数量方面也取得了巨大的成绩。但哔哩哔哩还在继续亏损&#xff0c;随着国家的监管环境朝着对游戏行业有利的方向变化&#xff0…
阅读更多...
【案例教程】GAMS电力模型

【案例教程】GAMS电力模型

本专题主要针对电力系统领域中比较典型的优化问题、优化方法及其在GAMS中的实现进行分析。共分为五个部分&#xff0c;包括电力系统机组组合专题、最优潮流专题、水电优化运行专题、鲁棒优化和多能源互补优化专题、分布鲁棒优化专题等&#xff0c;从基本模型到复杂模型逐步深入…
阅读更多...
MySql数据类型都是字符串(varchar),数据类型一样,但是联表查询不走索引,是什么原因呢

MySql数据类型都是字符串(varchar),数据类型一样,但是联表查询不走索引,是什么原因呢

大家都知道,如果联表查询中,数据类型不一样,是很有可能不走索引的,但是有时候数据类型一样也是有可能不走索引的,我们往下看1 数据准备我们准备两个表,用来模拟联表查询1.1 user表CREATE TABLE user (id bigint(20) NOT NULL AUTO_INCREMENT COMMENT 主键,phone varchar(20) DE…
阅读更多...
华为OD机试用Python实现 -【几何平均值最大子数组】| 2023年3月被抽中

华为OD机试用Python实现 -【几何平均值最大子数组】| 2023年3月被抽中

华为OD机试题 最近更新的博客华为 OD 机试 300 题大纲几何平均值最大子数组题目描述输入描述输出描述说明示例一输入输出说明示例二输入输出说明Python 代码实现核心逻辑最近更新的博客 华为od 2023 | 什么是华为od，od 薪资待遇，od机试题清单</
阅读更多...
测试只能干到35岁？35岁+的测试就会失业？

测试只能干到35岁？35岁+的测试就会失业？

互联网行业在很多年轻人的眼中&#xff0c;是高薪的象征。前几年的软件测试行业还是一个风口&#xff0c;随着不断地转行人员以及毕业的大学生疯狂地涌入软件测试行业&#xff0c;但是现在裁员潮涌现的时候&#xff0c;互联网行业首当其冲&#xff0c;互联网企业大量的裁员&…
阅读更多...
当你开始学习 Python 时，这是一个简单的学习计划及当你初学 Python 时，这里有几个建议

当你开始学习 Python 时，这是一个简单的学习计划及当你初学 Python 时，这里有几个建议

当你开始学习 Python 时&#xff0c;这是一个简单的学习计划&#xff1a; 1.入门 安装Python环境并熟悉基本的Python语法 熟悉Python的基本数据类型&#xff0c;例如数字、字符串和列表 学习控制流程&#xff0c;例如条件语句和循环语句 掌握函数和模块的基本知识 2.进阶 …
阅读更多...
Qt开发基本步骤示例：输入半径显示圆的面积

Qt开发基本步骤示例：输入半径显示圆的面积

目录 1. 创建一个新项目 1.1 创建类的基类 1.2 main.cpp代码释义 2. 代码写在哪&#xff1f; 2.1 怎么找到我们需要的函数&#xff1f; 1. 创建一个新项目 点击创建项目&#xff0c;开始创建&#xff1a; 1.1 创建类的基类 QMainWindow&#xff1a;带菜单栏的窗口QWidge…
阅读更多...
第一章——冯·诺伊曼结构计算机工作原理及层次结构分析

第一章——冯·诺伊曼结构计算机工作原理及层次结构分析

&#x1f3e1;个人主页 &#xff1a; 守夜人st &#x1f680;系列专栏&#xff1a;计算机组成原理 …持续更新中敬请关注… &#x1f649;博主简介&#xff1a;软件工程专业&#xff0c;在校学生&#xff0c;写博客是为了总结回顾一些所学知识点 目录第一章——冯诺伊曼结构计算…
阅读更多...
深入浅出RPC框架-学习笔记

深入浅出RPC框架-学习笔记

1 基本概念 1.1 本地函数调用 1.2 远程函数调用 1.3 RPC概念模型 5个模型组成&#xff1a;User、User-Stub、RPC-Runtime、Server-Stub、Server 1.4 一次RPC的完整过程 1.4.1 IDL (Interface description language)文件 IDL通过一种中立的方式来描述接口&#xff0c;使得在不…
阅读更多...
JavaScript（1）

JavaScript（1）

JavaScript简介 JavaScript是一门跨平台、面向对象的脚本语言&#xff0c;用来控制网页行为的&#xff0c;它能使网页可以交互。 JavaScript引入方式 1、内部脚本 将js代码定义在HTML页面中&#xff0c;在HTML中&#xff0c;JavaScript代码必须位于<script>与</scrip…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023