spring boot集成smart-doc自动生成接口文档详解

目录
  • 前言
  • 功能特性
    • 1 项目中创建 /src/main/resources/smart-doc.json配置文件
    • 2 配置内容如下(指定文档的输出路径)
    • 3 pom.xml下添加配置
    • 4 运行插件
    • 5 找到存放路径浏览器打开
    • 6 测试结果

前言

smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法。

smart-doc 完全基于接口源码分析来生成接口文档,完全做到零注解侵入,你只需要按照 java 标准注释编写,smart-doc 就能帮你生成一个简易明了的 markdown 或是一个像 GitBook 样式的静态 html 文档。如果你已经厌倦了 swagger 等文档工具的无数注解和强侵入污染,那请拥抱 smart-doc 吧!

功能特性

  • 支持接口 debug。
  • 零注解、零学习成本、只需要写标准 java 注释。
  • 基于源代码接口定义自动推导,强大的返回结构推导。
  • 支持 Spring MVC,Spring Boot,Spring Boot Web Flux (controller 书写方式),JAX-RS 规范。
  • 支持 Callable,Future,CompletableFuture 等异步接口返回的推导。
  • 支持 JavaBean 上的 JSR303 参数校验规范,支持分组验证。
  • 对 json 请求参数的接口能够自动生成模拟 json 参数。
  • 对一些常用字段定义能够生成有效的模拟值。
  • 支持生成 json 返回值示例。
  • 支持从项目外部加载源代码来生成字段注释 (包括标准规范发布的 jar 包)。
  • 支持生成多种格式文档:Markdown、HTML5、Asciidoctor、Postman collection、Open Api 3.0+。
  • 轻易实现在 Spring Boot 服务上在线查看静态 HTML5 api 文档。
  • 开放文档数据,可自由实现接入文档管理系统。
  • 一款代码注释检测工具,不写注释的小伙伴逃不过法眼了。
  • 插件式快速集成 (支持 maven 和 gradle 插件)。
  • 支持 Apache Dubbo rpc 文档生成。
  • 支持国产 Solon 应用开发框架。

smart-doc官网地址:Document

1 项目中创建 /src/main/resources/smart-doc.json配置文件

2 配置内容如下(指定文档的输出路径)

{
  "outPath": "D://md2"
}

3 pom.xml下添加配置

            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.1.0</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称-->
                    <projectName>测试</projectName>
                    <!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库
                         加载不到导致报错,这时请使用excludes排除掉-->
                    <excludes>
                        <!--格式为:groupId:artifactId;参考如下-->
                        <!--也可以支持正则式如:com.alibaba:.* -->
                        <exclude>com.alibaba:fastjson</exclude>
                    </excludes>
                    <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部
                       源代码而不是自动加载所有,因此使用时需要注意-->
                    <!--smart-doc能自动分析依赖树加载所有依赖源码,原则上会影响文档构建效
                       率,因此你可以使用includes来让插件加载你配置的组件-->
                    <includes>
                        <!--格式为:groupId:artifactId;参考如下-->
                        <!--也可以支持正则式如:com.alibaba:.* -->
                        <include>com.alibaba:fastjson</include>
                        <!-- 如果配置了includes的情况下, 使用了mybatis-plus的分页需要
                             include所使用的源码包 -->
                        <include>com.baomidou:mybatis-plus-extension</include>
                        <!-- 如果配置了includes的情况下, 使用了jpa的分页需要include所使用
                             的源码包 -->
                        <include>org.springframework.data:spring-data-commons</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal,可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

4 运行插件

5 找到存放路径浏览器打开

6 测试结果

到此这篇关于spring boot集成smart-doc自动生成接口文档详解的文章就介绍到这了,更多相关spring boot集成smart-doc 内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • Springboot引入hibernate配置自动建表并进行增删改查操作

    目录 前言 一.引入依赖 二.配置yml 三.写代码 四.测试结果 前言 有些业务比较复杂,比如我们需要新建10张表,每张表有10个字段,如果用手工来操作,肯定非常浪费时间,而且随着代码中对实体类的修改,还要同时修改数据库表,有时候写着写着就忘了,代码改了,数据库没改,这种问题使用 hibernate 的自动建表就好啦. 一.引入依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifac

  • idea快速实现将SpringBoot项目打包Docker镜像并部署

    目录 1.修改docker的配置文件 2.配置端口开放 3.IDEA安装Docker插件 4.IDEA配置docker 5.SpringBoot整合Docker配置 5.1 安装pom依赖 5.2 build镜像 5.3 启动镜像 1.修改docker的配置文件 修改文件信息路径如下:/etc/docker/daemon.json在配置文件中添加以下内容: "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/d

  • SpringBoot的API文档生成工具SpringDoc使用详解

    目录 前言 SpringDoc简介 使用 集成 从SpringFox迁移 结合SpringSecurity使用 测试 常用配置 总结 参考资料 前言 之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库,上了下官网发现已经有接近两年没出新版本了!前几天升级了SpringBoot 2.6.x 版本,发现这个库的兼容性也越来越不好了,有的常用注解属性被废弃了居然都没提供替代!无意中发现了另一款Swagger库SpringDoc,试用了一下非常不错,推荐给大家! Spr

  • SpringBoot打包docker镜像发布的详细步骤

    目录 1:首先构建一个SpringBoot项目 2:编写一个controller用于测试 3:本机启动观察是否能够成功访问 4:打包 5:找到生成的jar包位置 6:jar包的启动运行测试 7:编写Dockerfile文件 8:把我们的jar包和Dockerfile文件上传服务器 9:利用上传的文件构建镜像 10:利用镜像运行容器 11:测试访问 1:首先构建一个SpringBoot项目 只需要添加web依赖 2:编写一个controller用于测试 3:本机启动观察是否能够成功访问 4:打包

  • Rancher+Docker+SpringBoot实现微服务部署、扩容、环境监控

    目录 前言 一.前置需求 1.linux虚拟机或系统 2.创建好docker环境 3.写一个简单的微服务并创建为docker镜像 二.安装Rancher 1.拉取rancher镜像 2.启动rancher容器 3.访问rancher 三.配置rancher 1.把语言改为中文 2.创建rancher环境 3.添加一个主机 4.为主机添加应用 5.为应用添加服务 四.扩容 五.状态监控 1.查看 cpu.内存.网络.存储 状态 2.查看日志 六.访问控制 七.补充 前言 Rancher 是一套容器

  • Gitlab-runner+Docker实现自动部署SpringBoot项目

    目录 1.环境要求 当前我的服务版本 2.主要流程 3.GitlabRunner 安装和注册 3.1 安装 总结一共就2个步骤: 1.添加gitlab官方库: 2.命令安装: 3.2 开始注册 4.制作脚本! 重要!!! 3个文件位置图 .gitlab-ci.yml 5.测试 6.常见问题 本文基于Gitlab CI/CD及Docker快速实现项目的自动部署. 注意:本文较长,浏览需要12分钟左右. 1.环境要求 以下服务器的操作系统均为Centos7 服务器A:Gitlab 服务器B:Gitl

  • springboot-rabbitmq-reply 消息直接回复模式详情

    目录 一.使用场景 二.Reply实战 (1)依赖与YML配置 (2)RabbitMq bean配置 (3)消息生产端 (4)消息消费端 (1)方法一:sendTo注解+方法返回值 (2)方法二:读取生产端的消息使用模板发送 (3)方法三:方法返回值 (4)测试 一.使用场景 MQ的作用包括了解耦.异步等. 通常生产者只负责生产消息,而不关心消息谁去获取,或者消费结果如何:消费者只负责接收指定的消息进行业务处理而不关心消息从哪里来一级回复业务处理情况.但我们项目中有特殊的业务存在,我们作为消息生

  • SpringBoot父子线程数据传递的五种方案介绍

    目录 方案1.ThreadLocal+TaskDecorator 方案2.RequestContextHolder+TaskDecorator 方案3.MDC+TaskDecorator 方案4.InheritableThreadLocal 方案5.TransmittableThreadLocal 方案对比 简答说一下InheritableThreadLocal 总结 方案1.ThreadLocal+TaskDecorator 用户工具类 UserUtils /** *使用ThreadLocal

  • spring boot集成smart-doc自动生成接口文档详解

    目录 前言 功能特性 1 项目中创建 /src/main/resources/smart-doc.json配置文件 2 配置内容如下(指定文档的输出路径) 3 pom.xml下添加配置 4 运行插件 5 找到存放路径浏览器打开 6 测试结果 前言 smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法. smart-doc 完全基于

  • Spring Boot 集成 Mybatis Plus 自动填充字段的实例详解

    一般在表设计的时候,都会在表中添加一些系统字段,比如 create_time.update_time等. 阿里巴巴开发手册中也有这样的提示,如果对于这些公共字段可以进行统一处理,不需要每次进行插入或者更新操作的时候 set 一下,就可以提高开发效率,解放双手. 加入依赖 下面就通过 MyBatis Plus 来完成字段自动填充,首先加入 MyBatis Plus 依赖: <dependency>     <groupId>com.baomidou</groupId>  

  • SpringBoot如何自动生成API文档详解

    前言 在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写,高级一点的就采用API管理平台手工录入,一个项目有上千上万个接口,天啊,这是多么大的工作量,在接口维护的时候更加痛苦,为了解决这样的事我们可以借助 japi这个项目来完成RESTFul文档的自动生成,完全基于注释生成,更多详细配置可查看https://github.com/dounine/japi. 使用说明 克隆项目下来 git c

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • Go语言使用swagger生成接口文档的方法

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力. 最好是有一种方案能够既满足我们输出文档的需要又能

  • golang组件swagger生成接口文档实践示例

    目录 swagger介绍 gin-swagger实战 第一步:添加注释 第二步:生成接口文档数据 第三步:引入gin-swagger渲染文档数据 swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家

  • go swagger生成接口文档使用教程

    目录 前言 Swagger介绍 1.安装 2.检测是否安装成功 3.安装gin-swagger扩展 使用 1.添加注释 2.生成接口文档数据 3.引入gin-swagger渲染文档数据 总结 前言 这篇文章主要介绍了Go语言使用swagger生成接口文档的方法,希望能够对大家的学习或工作具有一定的帮助,需要的朋友可以参考下. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率.那如何维护接口文档,历来都是令人头痛的,感觉很浪费精力

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • Spring Boot整合mybatis并自动生成mapper和实体实例解析

    最近一直都在学习Java,发现目前Java招聘中,mybatis出现的频率挺高的,可能是目前Java开发中使用比较多的数据库ORM框架.于是我准备研究下Spring Boot和mybatis的整合. 1.在pom.xml文件中添加下面的配置 <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-

随机推荐