专栏首页A周立SpringCloud分享:手把手生成漂亮的静态文档说明页

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

最近经常被问 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部署了。

本文分享自微信公众号 - IT牧场(itmuch_com),作者:itmuch

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-08-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 译:在 Spring Boot 中使用 Spring AOP 和 AspectJ 来测量方法的执行时间

    原文链接:https://dzone.com/articles/logging-average-method-execution-times-via-aspec...

    用户1516716
  • 万亿条数据查询如何做到毫秒级响应?

    知乎,在古典中文中意为“你知道吗?”,它是中国的 Quora,一个问答网站,其中各种问题由用户社区创建,回答,编辑和组织。

    用户1516716
  • 盘点实现定时任务的那些方案

    节前有更新一篇定时任务的相关文章《延时消息之时间轮》,有朋友提出希望可以完整的介绍下常见的定时任务方案,于是便有了这篇文章。

    用户1516716
  • rpc框架: thrift/avro/protobuf 之maven插件生成java类

    thrift、avro、probobuf 这几个rpc框架的基本思想都差不多,先定义IDL文件,然后由各自的编译器(或maven插件)生成目标语言的源代码,但是...

    菩提树下的杨过
  • 运维:记录因grpc需求而引发的glibc故障

    提示glibc版本有问题,然后打算升级,glibc.结果把/lib64/libc.so.6 给替换了,造成Linux ssh无法远程登录,bash命令无法执行。

    heidsoft
  • 自定义maven项目结构-maven archtype

    背景 经常使用同一套类似的工程结构,就想着能不能自动构建,不用每次都进行工程结构的拷贝,另外呢也是想建立一套项目工程结构的规范,运用技术代替人工

    shengjk1
  • Maven管理多模块应用

    用户2193479
  • IDEA创建SpringBoot的多模块项目教程

    最近在写一个多模块的SpringBoot项目,基于过程总了一些总结,故把SpringBoot多个模块的项目创建记录下来。

    朱季谦
  • maven项目配置框架

    任何一个maven项目都会继承一个默认的父pom配置:Super POM,详见:https://maven.apache.org/guides/introduc...

    2Simple
  • 这个Maven依赖的问题,你敢说你没遇到过

    Maven 依赖没处理好的话经常会导致发生一些问题,非常烦。今天给大家分享一个依赖相关的问题,说不定你之前就遇到过。

    猿天地

扫码关注云+社区

领取腾讯云代金券