当前位置:网站首页>【已解决】如何生成漂亮的静态文档说明页
【已解决】如何生成漂亮的静态文档说明页
2022-07-06 01:19:00 【菜鸟是大神】
最近经常被问 ITMuch API 文档页是怎么制作的,考虑到步骤略复杂,写篇手记总结下吧。
TIPS
ITMuch API 是个人在慕课网视频《 面向未来微服务: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
加依赖
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
<!-- 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(按照自己的需要配置,下面的配置代码仅供参考)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
/** * @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注解
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
@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中添加如下内容:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <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等等。
这款插件还有很多使用姿势,详见 GitHub - Swagger2Markup/swagger2markup-maven-plugin: A Swagger2Markup Maven Plugin
生成HTML
下面,只需要将ASCIIDOC转换成html就OK了,在pom.xml中添加如下内容:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | <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
插件同样也有很多姿势,详见:GitHub - asciidoctor/asciidoctor-maven-plugin: A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.
生成的文件在 src/docs/asciidoc/html
(看你插件上面的配置哈),然后你就可以弄个NGINX部署了。
使用
- 启动应用
- 执行
mvn swagger2markup:convertSwagger2markup
生成ASCIIDOC - 执行
mvn asciidoctor:process-asciidoc
生成html
边栏推荐
- MATLB|实时机会约束决策及其在电力系统中的应用
- Spir - V premier aperçu
- Crawler request module
- 网易智企逆势进场,游戏工业化有了新可能
- Mysql--- query the top 5 students
- Finding the nearest common ancestor of binary search tree by recursion
- A glimpse of spir-v
- What is weak reference? What are the weak reference data types in ES6? What are weak references in JS?
- 黄金价格走势k线图如何看?
- Hundreds of lines of code to implement a JSON parser
猜你喜欢
Test de vulnérabilité de téléchargement de fichiers basé sur dvwa
关于softmax函数的见解
Recommended areas - ways to explore users' future interests
Unity | 实现面部驱动的两种方式
servlet(1)
1791. Find the central node of the star diagram / 1790 Can two strings be equal by performing string exchange only once
3D model format summary
Huawei converged VLAN principle and configuration
Differences between standard library functions and operators
激动人心,2022开放原子全球开源峰会报名火热开启
随机推荐
有谁知道 达梦数据库表的列的数据类型 精度怎么修改呀
Crawler request module
File upload vulnerability test based on DVWA
In the era of industrial Internet, we will achieve enough development by relying on large industrial categories
基於DVWA的文件上傳漏洞測試
Opinions on softmax function
Four commonly used techniques for anti aliasing
Docker compose配置MySQL并实现远程连接
yii中console方法调用,yii console定时任务
Condition and AQS principle
关于softmax函数的见解
Unity | two ways to realize facial drive
MUX VLAN configuration
Recursive method to realize the insertion operation in binary search tree
Building core knowledge points
1791. Find the central node of the star diagram / 1790 Can two strings be equal by performing string exchange only once
VMware Tools安装报错:无法自动安装VSock驱动程序
View class diagram in idea
视频直播源码,实现本地存储搜索历史记录
ThreeDPoseTracker项目解析