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

java生成文档生成样式结果:

1.pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.1.RELEASE</version>
    <relativePath/>
</parent>


<dependencies>

    <!-- SpringBoot整合Web组件 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.8</version>
    </dependency>

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


</dependencies>


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

        

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

    </plugins>
</build>

2.启动类

@SpringBootApplication
public class SwaggerDacApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDacApplication.class,args);
    }
}

3.实体类

@AllArgsConstructor
@NoArgsConstructor
@Builder
@Data
@ApiModel("公告")
public class Notice {
  /** * ID */ @ApiModelProperty("id")
  private Integer id;

   /** * 公告内容 */ @ApiModelProperty("公告内容")
  private String content;
}

4.controller

 /** * @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);
    }
}

使用生成html

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

1.打开命令工具

2.分别执行

mvn swagger2markup:convertSwagger2markup

mvn asciidoctor:process-asciidoc