真的别再用Swagger了，你知道为什么吗？

哈喽，大家好，我是了不起。

成都创新互联主要为客户提供服务项目涵盖了网页视觉设计、VI标志设计、全网整合营销推广、网站程序开发、HTML5响应式重庆网站建设公司、手机网站制作设计、微商城、网站托管及成都网站改版、WEB系统开发、域名注册、国内外服务器租用、视频、平面设计、SEO优化排名。设计、前端、后端三个建站步骤的完善服务体系。一人跟踪测试的建站服务标准。已经为电动窗帘行业客户提供了网站维护服务。

首先，Swagger 这个工具能够自动生成 API 接口文档，在线调试，节省了很多书写文档的时间，非常强大。

但是，想要文档生成的合格，还是要书写大量的注解。有没有一种连注解都不用写的方式呢？

smart-doc简介

今天了不起给大家推荐一个技术：smart-doc，看名字就知道，它是 智能-文档。直接分析代码，根据代码含义生成文档（开个玩笑，它还没有那么智能）；其实它是利用的注释，来生成文档，还是需要写注释的。

官方介绍：smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

swagger和smart-doc的对比

我们来看看swagger和smart-doc的区别

来看看smart-doc 的代码

如果是swagger 的写法，每个字段都要加上 @ApiModelProperty("xxx") 的注解，如果有几十个字段，几十个类，那代码量多的可不小。

不过这些类一般都是自动生成工具生成的，对写代码的人影响不大，不过这样子写倒是简洁了不少，甚得我意~

可能有人就说了，我不写注释，只写swagger注解，看起来也很简洁，这也确实没错。

确实看起来很简洁，不过没有文档注释的情况下，在其他类里你是看不到这个字段的解释的，每次找字段都得回到这个类看看到底是不是这个字段。如果你和同事们的英语都 very good，当我没说。

如果是api接口，smart-doc想要生成文档，需要写成这样（好像看起来什么都没写）

而swagger就需要加上@ApiOperation()这个注解，如果是个参数多的接口，还需要@ApiImplicitParams()这个注解，徒增学习成本

使用smart-doc

总共需要3步：

1.引入pom依赖，是一个插件

    com.github.shalousun
    smart-doc-maven-plugin
    ${smart-doc-plugin.version}
    
        
        ${basedir}/src/main/resources/smart-doc.json
        
        ${project.name}
        
            
            
            com.fu:common-.*
            com.fu:generator
        
    
    
        
            
            compile
            
                openapi
            
        
    

2.编写smart-doc.json文件

{
  // 参考文档：https://smart-doc-group.github.io/#/zh-cn/start/quickstart
  "outPath": "D:\\111",

  "coverOld": true,
  "allInOne": true, // 是否将文档合并到一个文件中，一般推荐为true
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "isStrict": false, //是否开启严格模式
  // controller包过滤，多个包用英文逗号隔开
  "packageFilters": "com.fu.system.controller.*",
  "projectName": "system",
  "sortByTitle": true, // 接口排序
  "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
    "javax.servlet.http.HttpServletRequest",
    "javax.servlet.http.HttpServletResponse",
    "javax.servlet.http.HttpSession"
   ]
}

3.运行这个插件，如果很熟悉mvn命令，在命令行运行它也行；可以生成openapi、postman、html、Markdown等各种格式的文档

关于pom 和 smart-doc.json 的配置，具体配置可前往官方文档查看：

https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc

文档自动化

如果它不能和swagger一样，自动部署文档，还得手动，那也不会来推荐这个了。

官方推荐方式：smart-doc + Torna 

需要额外部署一个 Torna 文档接口服务，类似 yapi；很多企业也都是单独部署的接口文档服务。

可以看出来界面比swagger好太多了

了不起这里给大家另一种方案，本地自动部署，smart-doc + apifox（postman应该也可以）

apifox -> 接口导入 -> 自动同步

这个数据源URL可以直接配置为 file:///D:/111/openapi.json，在你配置pom的时候，直接配置成编译项目时生成 openapi格式的文档，就可以自动部署到apifox，完美~

小结

今天了不起对这个smart-doc就介绍到这里了，感兴趣的小伙伴可以用起来了，对代码0侵入，简直太适合我这种强迫症患者了。

分享文章：真的别再用Swagger了，你知道为什么吗？
URL地址：http://www.shufengxianlan.com/qtweb/news18/271018.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联