转载

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

点击上方 "IT牧场" ，选择 "设为星标" 技术干货每日送达！

最近经常被问 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 加依赖

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<groupId>io.swagger</groupId>

<artifactId>swagger-annotations</artifactId>

</exclusion>

<groupId>io.swagger</groupId>

<artifactId>swagger-models</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

<groupId>io.swagger</groupId>

<artifactId>swagger-annotations</artifactId>

</dependency>

<groupId>io.swagger</groupId>

<artifactId>swagger-models</artifactId>

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

<groupId>io.github.swagger2markup</groupId>

<artifactId>swagger2markup-maven-plugin</artifactId>

<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>

<outputFile>src/docs/asciidoc/generated/all</outputFile>

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

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>

<outputDirectory>src/docs/asciidoc/html</outputDirectory>

<sourceHighlighter>coderay</sourceHighlighter>

</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速成（领域驱动设计速成）》 • 007：全部 • 008： 加技术讨论群