当前位置:网站首页>Please don't use swagger again. I'd like to recommend some online document generation artifact

Please don't use swagger again. I'd like to recommend some online document generation artifact

2020-12-08 11:53:48 Su San talks about technology

Preface

Recently, the company plans to make a openapi Open platform , Let me find a good online document generation tool , The specific requirements are as follows :

  1. It has to be open source
  2. It can generate online documents in real time
  3. Support full text search
  4. Support online debugging function
  5. Beautiful interface

Tell the truth , This requirement seems simple , But it's not easy at all .

I spent a few days everywhere Baidu , Google , Technology blogs and Forum Search Information , The following document generation tools have been investigated :

gitbook

github Address :github.com/GitbookIO/g…

Open source licenses :Apache-2.0 License

Star: 22.9k

development language :javascript

user :50 ten thousand +

Recommend index :***

The sample address :www.servicemesher.com/envoy/intro…

file

gitBook Is a document editing tool . Its function is similar to Jinshan WPS Medium word Or Microsoft office Medium word Document editing tools for . It can be used to write documents 、 Create a form 、 Insert picture 、 Generate pdf. Of course , The above functions WPS、office Maybe better , however ,gitBook There are even more powerful features : It can build a website with documents , Let more people know about your books , in addition , The most important thing is , He supported Git, That means , It is a distributed document editing tool . You can write your documents anytime, anywhere , It's also possible for multiple people to write documents together , Even if more than one person writes a document on the same page , It can also record everyone's content , And tell you the difference between them , It can also record every change you make , You can look at every note and change , Even if you delete the document , It can also be found ! This is what it inherits git The power of the latter !

advantage : It's very simple to use , Support full text search , Can follow git Perfect integration , There is no embeddedness in the code , Support markdown Format document writing .

shortcoming : Need to maintain a separate document project , If the interface changes , You need to manually modify this document project , Otherwise, there may be inconsistency between the interface and the document . also , Online debugging is not supported .

Personal advice : If there are few external interfaces , Or it doesn't change often after writing. You can use this .

smartdoc

gitee Address : gitee.com/smart-doc-t…

Open source licenses :Apache-2.0 License

Star: 758

development language :html、javascript

user : millet 、 Hkust xunfei 、1 Add

Recommend index :****

The sample address :gitee.com/smart-doc-t…

file

smart-doc It's a java restful api Document generation tool ,smart-doc Subvert the tradition, like swagger This kind of implementation method that uses annotation intrusion to generate documents .smart-doc The interface document is generated based on the analysis of interface source code , Completely zero annotation intrusion , Just follow java The writing of standard notes will give you a standard markdown Interface document .

advantage : Based on the analysis of interface source code to generate interface documents , Zero annotation intrusion , Support html、pdf、markdown Format file export .

shortcoming : Need to introduce extra jar package , Online debugging is not supported

Personal advice : If you generate documents in real time , But I don't want to make any extra comments , such as : Use swagger You need to type @Api、@ApiModel Etc , You can use this .

redoc

github Address :github.com/Redocly/red…

Open source licenses :MIT License

Star: 10.7K

development language :typescript、javascript

user :docker、redocly

Recommend index :****

The sample address :docs.docker.com/engine/api/…

file

redoc I claim to be the best online documentation tool . It supports swagger Interface data , Provides a variety of ways to generate documents , Very easy to deploy . Use redoc-cli Ability to bundle your documents to zero dependency HTML In file , Responsive three panel design , With a menu / Scroll sync .

advantage : Very easy to generate documents , Three panel design

shortcoming : Chinese search is not supported , It is divided into : Normal version and Paid version , The normal version does not support online debugging . in addition UI Interactive personal feeling is not suitable for the majority of domestic programmers operating habits .

Personal advice : If you want to quickly build a system based on swagger Documents , And it doesn't require online debugging , You can use this .

knife4j

gitee Address :gitee.com/xiaoym/knif…

Open source licenses :Apache-2.0 License

Star: 3k

development language :java、javascript

user : Unknown

Recommend index :****

The sample address :swagger-bootstrap-ui.xiaominfo.com/doc.html

file knife4j Is for Java MVC Framework for the integration Swagger Generate Api Document enhancement solution , Formerly known as swagger-bootstrap-ui, The name kni4j I hope she can be as small as a dagger , Light weight , And it's powerful .

advantage : be based on swagger Generate real-time online documents , Support online debugging , Global parameter 、 internationalization 、 Access control, etc , Very powerful .

shortcoming : The interface is a little ugly , Need to rely on extra jar package

Personal advice : If the company is right about ui It's not very demanding , This tool can be used to generate documents , The comparison function is more powerful .

yapi

github Address :github.com/YMFE/yapi

Open source licenses :Apache-2.0 License

Star: 17.8k

development language :javascript

user : tencent 、 Ali 、 Baidu 、 Jingdong and other large factories

Recommend index :*****

The sample address :yapi.fanruan.com/

file yapi It was developed and open source by the front-end team , It mainly supports the following functions :

  • Visual interface management
  • data mock
  • Automated interface testing
  • Data import ( Include swagger、har、postman、json、 Command line )
  • Rights management
  • Support localization deployment
  • Support plug-ins
  • Support secondary development

advantage : Very powerful , Support rights management 、 Online debugging 、 Interface automation testing 、 Plug in development, etc ,BAT Waiting for big factories to use , The function is very good .

shortcoming : Online debugging requires plug-ins to be installed , The user's physical examination is a little bit bad , Mainly to solve cross domain problems , There may be security issues . But to solve this problem , You can implement a plug-in by yourself , It shouldn't be difficult .

Personal advice : If you don't consider the security of plug-in security , This online documentation tool is still very easy to use , It can be said to be a artifact , I strongly recommend that .

apidoc

github Address :github.com/apidoc/apid…

Open source licenses :MIT License

Star: 8.7k

development language :javascript

user : Unknown

Recommend index :*****

The sample address :apidocjs.com/example/#ap…

file

apidoc It's a simple one RESTful API Document generation tool , It extracts content in a specific format from code comments and generates documents . Support such as Go、Java、C++、Rust And most development languages , You can use apidoc lang The command line looks at all the support lists .

apidoc It has the following characteristics :

  1. Cross platform ,linux、windows、macOS Such as support ;
  2. It supports a wide range of languages , Even if not , It's also easy to expand ;
  3. Support multiple projects in different languages to generate a document ;
  4. The output template can be customized ;
  5. Generate from documents mock data ;

advantage : Generating online documents based on code comments , Less embeddedness to code , Support for multiple languages , Cross platform , You can also customize the template . Support search and online debugging .

shortcoming : You need to add the specified annotation to the comment , If the code parameter or type is modified , It is necessary to modify the annotation content synchronously , There is a certain amount of maintenance work .

Personal advice : This online document generation tool provides another idea ,swagger It's to annotate the code , and apidoc It's adding data to annotations , Less code embeddedness , Recommended .

showdoc

github Address :github.com/star7th/sho…

Open source licenses :Apache Licence

Star: 8.1k

development language :javascript、php

user : exceed 10000+ The Internet team is using

Recommend index :*****

The sample address :www.showdoc.com.cn/demo?page_i…

file ShowDoc It's a perfect fit for IT Team's online document sharing tool , It can speed up the efficiency of communication between teams .

What functions does it have :

  1. Responsive Web Design , Project documents can be shared to a computer or mobile device for viewing . You can also export a project to word file , For offline browsing .
  2. Rights management ,ShowDoc There are two kinds of projects on the public project and private project . Public items can be accessed by any logged in and non logged in users , Private projects require password verification access . The password is set by the project Creator .
  3. ShowDoc use markdown Editor , Click the button at the top of the editor to insert API Interface template and data dictionary template .
  4. ShowDoc Provide historical version function for the page , You can easily restore the page to the previous version .
  5. Support file import , The file can be postman Of json file 、swagger Of json file 、showdoc Of markdown Compressed package , The system will automatically identify the file type .

advantage : Support project authority management , Multiple format file import , Full text search and other functions , It's very convenient to use . And support the deployment of their own servers , It also supports two ways of online hosting .

shortcoming : Online debugging is not supported

Personal advice : If online debugging is not required , This online documentation tool is worth using .

And finally ( Please pay attention to , Don't whore me for nothing )

If this article is helpful to you , Or if there's some inspiration , Help scan and issue QR code, pay attention to , Or like it 、 forward 、 Looking at . Reply in official account : interview 、 Code artifact 、 Development Manual 、 Time management has great fan benefits , Additional reply : Add group , We can communicate and learn from the predecessors of many big factories .

版权声明
本文为[Su San talks about technology]所创,转载请带上原文链接,感谢
https://chowdera.com/2020/12/202012081152190183.html