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

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

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

    
    
    
    
      io.springfox
      springfox-swagger2
      2.9.2
      
        
          io.swagger
          swagger-annotations
        
        
          io.swagger
          swagger-models
        
      
    
    
      io.springfox
      springfox-swagger-ui
      2.9.2
    
    
      io.swagger
      swagger-annotations
      1.5.21
    
    
      io.swagger
      swagger-models
      1.5.21
    
    
  • 配置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中添加如下内容:


  
    
      io.github.swagger2markup
      swagger2markup-maven-plugin
      1.3.1
      
        
        http://localhost:8080/v2/api-docs
        
        src/docs/asciidoc/generated/all
        
          
          ASCIIDOC
          TAGS
        
      
    
    ...

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

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

生成HTML

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


  
    
      org.asciidoctor
      asciidoctor-maven-plugin
      1.5.6
      
        
        src/docs/asciidoc/generated
        
        src/docs/asciidoc/html
        html
        coderay
        
        
          book
          left
          3
          
          
          
          
        
      
    

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

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

使用

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

你可能感兴趣的:(dubbo,java)