如何生成漂亮的靜態文檔說明頁

生成結果樣式

項目結構

 

 

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

@RestController
@RequestMapping("/notices")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
@Api(tags = "公告相關接口", description = "公告相關接口")
public class NoticeController {
    /**
     * 查詢最新的一條公告
     *
     * @return 公告列表
     */
    @GetMapping("/newest")
    @ApiOperation(value = "查詢最新的一條公告", notes = "用於：公告")
    public Notice findNewest() {

        return new Notice();
    }

}

5.config

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