如何生成漂亮的静态文档说明页

分享:如何生成漂亮的静态文档说明页

最近经常被问 https://t.itmuch.com/doc.html 文档页是怎么制作的,考虑到步骤略复杂,写篇手记总结下吧。

TIPS

https://t.itmuch.com/doc.html 是个人在慕课网视频《 面向未来微服务:Spring Cloud Alibaba从入门到进阶 》的实战项目配套文档。

效果

效果

总体步骤

  • 整合Swagger,生成Swagger描述端点 /v2/api-docs
  • 使用 swagger2markup-maven-plugin ,将 /v2/api-docs 生成ASCIIDOC文件;
  • 使用 asciidoctor-maven-plugin ,将ASCIIDOC文件转换成HTML;
  • 部署

整合Swagger

TIPS

Swagger的使用非常简单,本文不展开探讨了,各位看官自行百度一下用法吧。

常用注解:

  • @Api
  • @ApiOperation
  • @ApiModel
  • @ApiModelProperty
  • 加依赖

    <!-- swagger -->
    <!-- 之所以要排除,是因为如果不排除会报NumberFormatException的警告。 -->
    <!-- 参考:https://github.com/springfox/springfox/issues/2265-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
      <exclusions>
        <exclusion>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-models</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>1.5.21</version>
    </dependency>
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
      <version>1.5.21</version>
    </dependency>
    
  • 配置Swagger(按照自己的需要配置,下面的配置代码仅供参考)

    /**
     * @author itmuch.com
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfiguration {
        /**
         * swagger 信息
         *
         * @return 页面信息
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("ITMuch API")
                    .description("ITMuch API")
                    .termsOfServiceUrl("")
                    .version("1.0.0")
                    .contact(new Contact("", "", "")).build();
        }
    
        @Bean
        public Docket customImplementation() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.itmuch"))
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(this.apiInfo());
                    //.globalOperationParameters(parameters);
        }
    }
    
  • 为接口Swagger注解

    @RestController
    @RequestMapping("/notices")
    @RequiredArgsConstructor(onConstructor = @__(@Autowired))
    @Api(tags = "公告相关接口", description = "公告相关接口")
    public class NoticeController {
        /**
         * 查询最新的一条公告
         *
         * @return 公告列表
         */
        @GetMapping("/newest")
        @ApiOperation(value = "查询最新的一条公告", notes = "用于:公告")
        public Notice findNewest() {
            return new Notice();
        }
    }
    
    
    @AllArgsConstructor
    @NoArgsConstructor
    @Builder
    @Data
    @ApiModel("公告")
    public class Notice {
      /**
       * ID
       */
      @ApiModelProperty("id")
      private Integer id;
    
      /**
       * 公告内容
       */
      @ApiModelProperty("公告内容")
      private String content;
      ...
    }
    
  • 这样,应用启动完成后,就会有一个 /v2/api-docs 端点,描述了你的API的信息。

生成ASCIIDOC

在pom.xml中添加如下内容:

<build>
  <plugins>
    <plugin>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup-maven-plugin</artifactId>
      <version>1.3.1</version>
      <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档,输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
          <!-- ascii格式文档 -->
          <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
          <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
      </configuration>
    </plugin>
    ...

swagger2markup-maven-plugin 插件的作用是读取 http://localhost:8080/v2/api-docs 的信息,生成ASCIIDOC文档。当然你也可以生成其他格式,比如Markdown等等。

这款插件还有很多使用姿势,详见 https://github.com/Swagger2Markup/swagger2markup-maven-plugin

生成HTML

下面,只需要将ASCIIDOC转换成html就OK了,在pom.xml中添加如下内容:

<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>1.5.6</version>
      <configuration>
        <!-- asciidoc文档输入路径 -->
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <!-- html文档输出路径 -->
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <!-- html文档格式参数 -->
        <attributes>
          <doctype>book</doctype>
          <toc>left</toc>
          <toclevels>3</toclevels>
          <numbered></numbered>
          <hardbreaks></hardbreaks>
          <sectlinks></sectlinks>
          <sectanchors></sectanchors>
        </attributes>
      </configuration>
    </plugin>

asciidoctor-maven-plugin 插件同样也有很多姿势,详见:https://github.com/asciidoctor/asciidoctor-maven-plugin

生成的文件在 src/docs/asciidoc/html (看你插件上面的配置哈),然后你就可以弄个NGINX部署了。

使用

  • 启动应用
  • 执行 mvn swagger2markup:convertSwagger2markup 生成ASCIIDOC
  • 执行 mvn asciidoctor:process-asciidoc 生成html

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

如若内容造成侵权/违法违规/事实不符,请联系我们进行投诉反馈qq邮箱809451989@qq.com,一经查实,立即删除!

相关文章

二叉树堆的应用实例分析:堆排序 | TOP-K问题

&#x1f4f7; 江池俊&#xff1a; 个人主页 &#x1f525;个人专栏&#xff1a; ✅数据结构冒险记 ✅C语言进阶之路 &#x1f305; 有航道的人&#xff0c;再渺小也不会迷途。 文章目录 前言一、堆排序1.1 排序思想1.2 堆排序过程&#xff08;图解&#xff09;1.3 堆排序代…

C++ 数论相关题目(欧拉函数、筛法求欧拉函数)

1、欧拉函数 给定 n 个正整数 ai &#xff0c;请你求出每个数的欧拉函数。 欧拉函数的定义 1∼N 中与 N 互质的数的个数被称为欧拉函数&#xff0c;记为 ϕ(N) 。 若在算数基本定理中&#xff0c;Npa11pa22…pamm &#xff0c;则&#xff1a; ϕ(N) Np1−1p1p2−1p2…pm−1p…

【数学建模】插值与拟合

文章目录 插值插值方法用Python解决插值问题 拟合最小二乘拟合数据拟合的Python实现 适用情况 处理由试验、测量得到的大量数据或一些过于复杂而不便于计算的函数表达式时&#xff0c;构造一个简单函数作为要考察数据或复杂函数的近似 定义 给定一组数据&#xff0c;需要确定满…

b+树的理解

二叉树&#xff1a; 每个节点支持两个分支的树结构&#xff0c;相比于单向链表&#xff0c;多了一个分支。 二叉查找树&#xff1a; 在二叉树的基础上增加了一个规则&#xff0c;左子树的所有节点都小于它的根节点&#xff0c;右子树的所有节点都大于他的根节点。 二叉查找树…

Flutter中实现中国省份地图

效果展示(这里只展示局部&#xff0c;完全展示违规)&#xff1a; 可以点击省份改变颜色&#xff0c;更多功能可以自行拓展。 注&#xff1a;非完整中国地图&#xff01;&#xff01;&#xff01; 本文用于记录在Flutter项目中安卓端实现中国地图&#xff0c;因为实现过程是通过…

分类预测 | Matlab实现GRU-Attention-Adaboost基于门控循环单元融合注意力机制的Adaboost数据分类预测/故障识别

分类预测 | Matlab实现GRU-Attention-Adaboost基于门控循环单元融合注意力机制的Adaboost数据分类预测/故障识别 目录 分类预测 | Matlab实现GRU-Attention-Adaboost基于门控循环单元融合注意力机制的Adaboost数据分类预测/故障识别分类效果基本描述程序设计参考资料 分类效果 …

【Linux C | 进程】Linux 进程间通信的10种方式(2)

&#x1f601;博客主页&#x1f601;&#xff1a;&#x1f680;https://blog.csdn.net/wkd_007&#x1f680; &#x1f911;博客内容&#x1f911;&#xff1a;&#x1f36d;嵌入式开发、Linux、C语言、C、数据结构、音视频&#x1f36d; &#x1f923;本文内容&#x1f923;&a…

手写一个图形验证码

文章目录 需求分析 需求 使用 JS 写一个验证码&#xff0c;并在前端进行校验 分析 新建文件 VueImageVerify.vue <template><div class"img-verify"><canvas ref"verify" :width"state.width" :height"state.height&qu…

OpenCV-Python(51):基于Haar特征分类器的面部检测

目标 学习了解Haar 特征分类器为基础的面部检测技术将面部检测扩展到眼部检测等。 基础 以Haar 特征分类器为基础的对象检测技术是一种非常有效的对象检测技术(2001 年Paul_Viola 和Michael_Jones 提出)。它是基于机器学习的,通过使用大量的正负样本图像训练得到一个cascade_…

socket以及字节序

1. socket 介绍&#xff1a; 简介&#xff1a; 所谓 socket&#xff08; 套接字&#xff09;&#xff0c;就是对网络中不同主机上的应用进程之间进行双向通信的 端点的抽象。 一个套接字就是网络上进程通信的一端&#xff0c;提供了应用层进程利用网络协议交换数据的机制。从所…

推荐一个还可以的windows ssh工具

1.下载 https://github.com/kingToolbox/WindTerm/releases 2.解压 3.使用 上传 下载都很快 比cmd窗口好用 当然和finalshell有点像

Linux编辑器vim(含vim的配置)

文章目录 前言vim的基本概念vim基本操作进入vim模式切换退出vim vim指令vim命令模式指令vim底行模式命令 简单vim配置 前言 本篇文章&#xff0c;小编将介绍Linux编辑器–>vim以及vim的配置。 vim的基本概念 正常/普通/命令模式(Normal mode) 控制屏幕光标的移动&#xf…

云贝教育 |【分享课】1月25日Oracle分享主题:Oracle 单实例DG

分享主题&#xff1a;Oracle 19c 单实例DG-1 讲师&#xff1a;刘峰 直播时间&#xff1a;1月25日周四19:30 直播平台&#xff1a;微信视频号 云贝学院

(更新)“高铁开通”地级市-多期DID工具变量(2000-2022年)

参照卞元超&#xff08;2019&#xff09;、邓慧慧&#xff08;2020&#xff09;、汪克亮&#xff08;2021&#xff09;等人做法&#xff0c;将开通高铁的城市作为处理组&#xff0c;未开通高铁的城市作为对照组。地级市开通高铁之后的DID赋值为1&#xff0c;未开通则赋值为0 一…

云计算中的出口数据是指什么?

谷歌云&#xff08;Google Cloud&#xff09;近日宣布了一项重大政策变动&#xff0c;决定免除那些选择终止使用其服务并将数据迁移到其他云服务商或本地环境的客户的出口数据费用&#xff08;数据导出费用&#xff09;。 这一举措由谷歌云平台负责人阿米特扎维里&#xff08;A…

docker 基础手册

文章目录 docker 基础手册docker 容器技术镜像与容器容器与虚拟机docker 引擎docker 架构docker 底层技术docker 二进制安装docker 镜像加速docker 相关链接docker 生态 docker 基础手册 docker 容器技术 开源的容器项目&#xff0c;使用 Go 语言开发原意“码头工人”&#x…

SpringBoot责任链与自定义注解:优雅解耦复杂业务

引言 责任链模式是一种行为设计模式&#xff0c;它允许你将请求沿着处理者链进行传递&#xff0c;直到有一个处理者处理请求。在实际应用中&#xff0c;责任链模式常用于解耦发送者和接收者&#xff0c;使得请求可以按照一定的规则被多个处理者依次处理。 首先&#xff0c;本…

【LeetCode】104. 二叉树的最大深度(简单)——代码随想录算法训练营Day16

题目链接&#xff1a;104. 二叉树的最大深度 题目描述 给定一个二叉树 root &#xff0c;返回其最大深度。 二叉树的 最大深度 是指从根节点到最远叶子节点的最长路径上的节点数。 示例 1&#xff1a; 输入&#xff1a;root [3,9,20,null,null,15,7] 输出&#xff1a;3示例…

Docker网络配置与自定义IP容器通信

目录 前言 一、docker网络配置 1. bridge 虚拟网桥 2. host 网络模式 3. none 网络模式 4. 自定义container网络模式 二、自定义IP容器通信 1. 自定义IP 2. 创建所需容器&#xff08;mysql&#xff0c;tomcat&#xff09; 3. 准备项目资源 4. 构建Nginx实现负载均衡…

垃圾回收小程序:环保与便捷的完美结合

一、引言 随着科技的发展&#xff0c;移动应用程序已经成为人们日常生活中不可或缺的一部分。其中&#xff0c;废品回收小程序以其独特的价值和功能&#xff0c;日益受到人们的关注和青睐。本文将探讨废品回收小程序开发的重要性、功能特点、技术实现和未来发展趋势。 二、废…