利用Swagger自动生成漂亮的静态开发文档说明页

效果

利用Swagger自动生成漂亮的静态文档说明页

地址：https://t.itmuch.com/doc.html

 

总体步骤

•整合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 加依赖

 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

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中添加如下内容：

 
 
 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[2]

生成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[3]

生成的文件在 src/docs/asciidoc/html （看你插件上面的配置哈），然后你就可以弄个NGINX部署了。参考：www.qiyehao.cc