最新公告
  • 新注册用户请前往个人中心绑定邮箱以便接收相关凭证邮件!!!点击前往个人中心
  • 利用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静态文档教程

    常见问题FAQ

    如果资源链接失效了怎么办?
    本站用户分享的所有资源都有自动备份机制,如果资源链接失效,请联系本站客服QQ:2580505920更新资源地址。
    如果用户分享的资源与描述不符怎么办?
    可以联系客服QQ:2580505920,如果要求合理可以安排退款或者退赞助积分。
    如何分享个人资源获取赞助积分或其他奖励?
    本站用户可以分享自己的资源,但是必须保证资源没有侵权行为。点击个人中心,根据操作填写并上传即可。资源所获收益完全归属上传者,每周可申请提现一次。
    如果您发现了本资源有侵权行为怎么办?
    及时联系客服QQ:2580505920,核实予以删除。

    参与讨论

    • 211会员总数(位)
    • 3737资源总数(个)
    • 0本周发布(个)
    • 0 今日发布(个)
    • 919稳定运行(天)

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

    立即加入 了解更多
    成为赞助用户享有更多特权立即升级