利用Swagger2Markup生成HTML,markdown,confluence静态文档教程

常用注解速查

  • @Api 用在请求类上,表示对类的说明

    • tags说明该类的作用,可以在UI界面上看到的注解
    • value 该参数没什么意义,在UI界面上也看到,所以不需要配置
  • @ApiOperation用在请求的方法上,说明方法的用途

    • value说明方法的用途,此说明再xxx-controller下,点击才能看到
    • notes方法的备用说明,当有此值时:该接口说明会到页面中的主界面上
    • tags此参数不应该用到方法上,不然会在首页中独立展示为一个接口,这个接口与存在在controller文件中的接口描述相同,冗余
  • @ApiParam()用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)

    • name参数名
    • value参数说明
    • required是否必填
  • @ApiImplicitParams用在请求的方法上,表示一组参数说明,@ApiImplictParam包含在里面

  • @ApiImplictParam用在@ApliImplicitParams注解中,指定一个请求参数的各个方面

    • name参数名

    • value参数说明。

    • required是否必传

    • paramType参数类型(参数放置的位置)

      • header请求参数的获取 @RequestHeader
      • query请求参数的获取 @RequestParam
      • path用于Restful接口,请求参数的获取@PathVariable
      • body不常用
      • form不常用
    • dataType数据类型。默认String,其他值DataType = “Integer”

    • defaultValue参数的默认值

  • @ApiResponses用在请求的方法上,表示一组响应,@ApiResponse包含在里面

  • @ApiResponse用在@APIResponses中,一般用于表达一个错误的响应信息

    • code数字,例如400
    • message信息,例如“请求参数没有填好”
    • response抛出异常的类
  • @ApiModel用于响应类上,表示一个返回响应数据的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时

    • value表示对象名,可省略
    • description描述,可省略
  • @ApiModelProperty用在属性上,描述响应类的属性

    • value字段说明
    • name重写属性名字
    • dataType重写属性类型
    • required是否必填
    • example举例说明
    • hidden隐藏
  • @ApiIgnore忽视方法(不在UI界面上展示这个方法)

  • @ApiResponses响应集配置,与Controller中的方法并列使用

  • @ApiResponse响应配置,与Controller中的方法并列使用

    • codehttp状态码
    • message描述
    • response默认响应类void
  • @ResponseHeader与Controller中的方法并列使用

    • name响应头名称
    • description头描述
    • response默认响应类void

生成静态文档

​ 前后端分离场景下,可以使用Swagger构建API文档,但是在项目中我们必须通过整合swagger-ui,或使用单独部署的swagger-ui和/v2/api-docs返回的配置信息才能展现出所构建的API文档。

​ 本文将介绍一种生成静态API文档的方法,以便于构建更轻量部署和使用的API文档。

Swagger2Markup

​ Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。

项目主页:https://github.com/Swagger2Markup/swagger2markup

生成AsciiDoc

​ 1、首先准备一个已经使用了Swagger2的web项目,使用了spring-boot-starter-swagger也可以。

方式一

​ 1.直接通过Maven插件来生成,在pom.xml中增加如下插件来完成静态内容的生成。

<plugin>
	<groupId>io.github.swagger2markup</groupId>
	<artifactId>swagger2markup-maven-plugin</artifactId>
	<version>1.3.1</version>
	<configuration>
		<!--1、源路径-->
		<swaggerInput>填写URL</swaggerInput>
		<!--2、输出路径-->
		<outputDir>src/docs/asciidoc/generated</outputDir>
		<!--3、输出到一个文件-->
		<outputFile>src/docs/asciidoc/generated/all</outputFile>
		<config>
			<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
		</config>
	</configuration>
</plugin>

<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>
			<toc>left</toc>
		</attributes>
	</configuration>
</plugin>
  • MarkupLanguage.ASCIIDOC:指定了要输出的最终格式。除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"):指定了生成静态部署文档的源头配置,可以是这样的URL形式,也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目,我们通过使用访问本地Swagger接口的方式,如果是从外部获取的Swagger文档配置文件,就可以通过字符串或读文件的方式
  • toFolder(Paths.get("src/docs/asciidoc/generated"):指定最终生成文件的具体目录位置
  • 如果不想分割结果文件,也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")toFile(Paths.get("src/docs/asciidoc/generated/all")),将转换结果输出到一个单一的文件中,这样可以最终生成html的也是单一的。

​ 2.点击Maven插件列表的swagger2markup:convertSwagger2markup按钮

​ 会在src目录下生成一个doc文件夹。

​ 3、点击asciidoctor:process-asciidoc即可在src/docs/asciidoc/html生成静态HTML文件

​ 4、打开paths.html即可

注意:

1、需要先运行项目,然后再执行Maven插件的快捷方式按钮

2、源地址URL不支持中文,但是可以将汉字转换成UTF-8编码如http://localhost:9933/v2/api-docs?group=9%E6%B6%89%E6%A1%88%E8%B4%A2%E7%89%A9

​ 5、效果如下(有裁剪)

方式二:查看下方参考资料1

​ 通过编写TEST类来执行生成文档的方式,但是我集成的时候出现了报错。

生成markdown文档或confluence

​ 依旧采用Maven插件的方式生成,在pom.xml里替换对应位置即可,有如下选择MARKDOWN生成markdown文件,扩展名为md;CONFLUENCE_MARKUP生成confluence代码,扩展名为txt;

<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage>

​ 然后同样点击swagger2markup:convertSwagger2markup按钮即可。

部署方式

​ markdown的可以通过Hexo、Jekyll实现静态化部署,下面主要介绍confluence的部署。

​ 登录confluence,选择新建页面,选中wiki标记,然后粘贴刚才生成的confluence的txt文件里的内容,保存即可。

参考资料

本站所有文章均由网友分享,仅用于参考学习用,请勿直接转载,如有侵权,请联系网站客服删除相关文章。若由于商用引起版权纠纷,一切责任均由使用者承担
极客文库 » 利用Swagger2Markup生成HTML,markdown,confluence静态文档教程

Leave a Reply

欢迎加入「极客文库」,成为原创作者从这里开始!

立即加入 了解更多