分享：手把手生成漂亮的靜態文檔說明頁技术頭條網

分享：手把手生成漂亮的靜態文檔說明頁

2019-08-26 15:53:44 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 加依賴




<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>
 
 <swaggerinput>http://localhost:8080/v2/api-docs/<swaggerinput>
 
 <outputfile>src/docs/asciidoc/generated/all/<outputfile>
 <config>
 
 <swagger2markup.markuplanguage>ASCIIDOC/<swagger2markup.markuplanguage>
 <swagger2markup.pathsgroupedby>TAGS/<swagger2markup.pathsgroupedby>
 /<config>
 /<configuration>
 /<plugin>
 ...
/<plugins>/<build>

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>
 
 <sourcedirectory>src/docs/asciidoc/generated/<sourcedirectory>
 
 <outputdirectory>src/docs/asciidoc/html/<outputdirectory>
 <backend>html/<backend>
 <sourcehighlighter>coderay/<sourcehighlighter>
 
 <attributes>
 <doctype>book/<doctype>
 left
 <toclevels>3/<toclevels>
 <numbered>
 <hardbreaks>
 <sectlinks>
 <sectanchors>
 /<attributes>
 /<configuration>
 /<plugin>
/<plugins>/<build>