百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 编程网 > 正文

分享:手把手生成漂亮的静态文档说明页

yuyutoo 2024-10-12 01:55 2 浏览 0 评论

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

TIPS

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

效果

总体步骤

?整合Swagger,生成Swagger描述端点 /v2/api-docs

?使用 swagger2markup-maven-plugin ,将 /v2/api-docs 生成ASCIIDOC文件;

?使用 asciidoctor-maven-plugin ,将ASCIIDOC文件转换成HTML;

?部署

整合Swagger

TIPS

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

常用注解:

?@Api

?@ApiOperation

?@ApiModel

?@ApiModelProperty

1 加依赖

<!-- 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>

2 配置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);
 }
}

3 为接口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[2]

生成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[3]

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

干货分享

最近将个人学习笔记整理成册,使用PDF分享。关注我,回复如下代码,即可获得百度盘地址,无套路领取!

?001:《Java并发与高并发解决方案》学习笔记;

?002:《深入JVM内核——原理、诊断与优化》学习笔记;

?003:《Java面试宝典》

?004:《Docker开源书》

?005:《Kubernetes开源书》

?006:《DDD速成(领域驱动设计速成)》


References

[1] 面向未来微服务:Spring Cloud Alibaba从入门到进阶: https://coding.imooc.com/class/358.html

[2]: https://github.com/Swagger2Markup/swagger2markup-maven-plugin

[3]: https://github.com/asciidoctor/asciidoctor-maven-plugin

相关推荐

野路子科技!2步教你把手机改造成一个FTP服务器,支持PC互传

哈喽,大家好,我是野路子科技,今天来给大家带来一个教程,希望大家喜欢。正如标题所言,就是教大家如何把售价改造成FTP服务器,而这个时候估计有朋友会问了,把手机改造成FTP服务器有什么用呢?现在有Q...

不得不看:别样于Server-U的群晖文件存储服务器的搭建与使用

我先前的作品中,有着关于Server-U的ftp文件存储服务器的搭建与访问的头条文章和西瓜视频,而且我们通过各种方式也给各位粉丝介绍了如何突破局域网实现真正意义上的公网访问机制技术。关于Server-...

Qt三种方式实现FTP上传功能_qt引入qftp库

FTP协议FTP的中文名称是“文件传输协议”,是FileTransferProtocol三个英文单词的缩写。FTP协议是TCP/IP协议组中的协议之一,其传输效率非常高,在网络上传输大的文件时,经...

Filezilla文件服务器搭建及客户端的使用

FileZilla是一个免费开源的FTP软件,分为客户端版本和服务器版本,具备所有的FTP软件功能。可控性、有条理的界面和管理多站点的简化方式使得Filezilla客户端版成为一个方便高效的FTP客户...

美能达柯美/震旦复印机FTP扫描怎么设置?

好多网友不知道怎么安装美能达/震旦复印机扫描,用得最多是SMB和FTP扫描,相对于SMB来说,FTP扫描安装步骤更为便捷,不容易出问题,不需要设置文件夹共享,所以小编推荐FTP来扫描以美能达机器为例详...

CCD(简易FTP服务器软件)_简单ftp服务器软件

CCD简易FTP服务器软件是一款很方便的FPT搭建工具,可以将我们的电脑快速变成一个FPT服务器。使用方法非常简单,只要运行软件就会自动生效,下载银行有该资源。该工具是不提供操作界面的,其他用户可以输...

Ubuntu系统搭建FTP服务器教程_ubuntu架设服务器

在Ubuntu系统上搭建FTP服务器是文件传输的一个非常实用方法,适合需要进行大量文件交换的场景。以下是一步步指导,帮助您在Ubuntu上成功搭建FTP服务器。1.安装vsftpd软件...

理光FTP扫描设置教程_理光ftp扫描设置方法

此教程主要用来解决WIN10系统下不能使用SMB文件夹扫描的问题,由于旧的SMB协议存在安全漏洞,所以微软在新的系统,WIN8/WIN10/SERVER201220162018里使用了新的SMB传...

纯小白如何利用wireshark学习网络技术

写在前面工欲善其事必先利其器!熟悉掌握一种神器对以后的工作必然是有帮助的,下面我将从简单的描述Wireshark的使用和自己思考去写,若有错误或不足还请批评指正。...

京东买13盘位32GB内存NAS:NAS系统安装设置教程

本内容来源于@什么值得买APP,观点仅代表作者本人|作者:yasden你没有看错,我在京东自营商城购买硬件,组装了一台13盘位,32GB内存的NAS,硬盘有13个盘位!CPU是AMD的5500!本文...

FileZilla搭建FTP服务器图解教程_filezilla server搭建ftp服务器

...

python教程之FTP相关操作_python ftps

ftplib类库常用相关操作importftplibftp=ftplib.FTP()ftp.set_debuglevel(2)#打开调试级别2,显示详细信息ftp.connect(“I...

xftp怎么用,xftp怎么用,具体使用方法

Xftp是一款界面化的ftp传输工具,用起来方便简单,这里为大家分享下Xftp怎么使用?希望能帮到有需要的朋友。IIS7服务器管理工具可以批量管理、定时上传下载、同步操作、数据备份、到期提醒、自动更新...

树莓派文件上传和下载,详细步骤设置FTP服务器

在本指南中,详细记录了如何在树莓Pi上设置FTP。设置FTP可以在网络上轻松地将文件传输到Pi上。FTP是文件传输协议的缩写,只是一种通过网络在两个设备之间传输文件的方法。还有一种额外的方法,你可以用...

win10电脑操作系统,怎么设置FTP?windows10系统设置FTP操作方法

打印,打印,扫描的日常操作是每一个办公工作人员的必需专业技能,要应用FTP作用扫描文件到电脑上,最先要必须一台可以接受文件的FTP服务器。许多软件都需要收费标准进行,但人们还可以应用Windows的系...

取消回复欢迎 发表评论: