preface

Recently, the company planned to build an OpenAPI open platform, and asked me to find an easy online document generation tool. The specific requirements are as follows:

  1. Must be open source
  2. Ability to generate online documents in real time
  3. Support full text search
  4. Supports online debugging
  5. Beautiful interface

To be honest, this requirement looks simple, but it’s not simple at all.

I spent several days searching for information on Baidu, Google, technical blogs and forums, and successively investigated the following document generation tools:

gitbook

Github address: github.com/GitbookIO/g…

Open source License: Apache-2.0 License

Star: 22.9 k

Development language: javascript

Users: 500,000 +

★★★

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

GitBook is a document editing tool. Its function is similar to word in Golden Mountain WPS or Microsoft Office Word document editing tool. It can be used to write documents, create tables, insert images, and generate PDFS. Of course, WPS and Office may do better than this, but gitBook has the most powerful features: it can build a website with documents, let more people know about your book, and most importantly, it supports Git, which means it is a distributed document editing tool. You can to write your document at any time and place, can be more than a joint document, even if many people write to the same page document, it also can record everyone’s content, and then tell you the difference between them, also can record every time you change, you can view every written records and change, even if the document you are deleted, it can also be retrieved! This is how it inherits Git!

Pros: Very simple to use, full text search support, perfect integration with Git, no embedding of code, markdown format documentation.

Disadvantages: You need to maintain a separate document project. If the interface is modified, you need to manually modify the document project. Otherwise, the interface may be inconsistent with the document. Online debugging is not supported.

Personal advice: Use this if you have few external interfaces, or don’t change much after writing.

smartdoc

Gitee address: gitee.com/smart-doc-t…

Open source License: Apache-2.0 License

Star: 758

Development language: HTML, javascript

Users: Xiaomi, IFlytek, 1 Plus

★★★★ ★

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

Smart-doc is a Java restful API document generation tool. Smart-doc subverts the traditional implementation of swagger, which uses extensive annotation intrusion to generate documents. Smart-doc generates the interface document entirely based on the source code analysis of the interface, completely without annotation intrusion, just need to write according to the Java standard annotation can get a standard Markdown interface document.

Advantages: generate interface documents based on interface source code analysis, zero annotation invasion, support HTML, PDF, Markdown format file export.

Disadvantages: Additional JAR packages need to be introduced and no online debugging is supported

Personal advice: Use this if you are generating documentation in real time but don’t want to add extra annotations, such as @API, @APIModel, etc., to use Swagger.

redoc

Github address: github.com/Redocly/red…

Open source License: MIT License

Star: 10.7 K

Development languages: typescript, javascript

Users: Docker, redocly

★★★☆

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

Redoc itself claims to be one of the best documentation tools available online. It supports Swagger interface data, provides multiple ways to generate documents, and is very easy to deploy. Use Redoc-CLI to bundle your documents into a zero-dependency HTML file with a responsive three-panel design with menu/scroll synchronization.

Advantages: Very easy to generate documents, three panel design

Disadvantages: Does not support Chinese search, including the common version and paid version. The common version does not support online debugging. In addition, UI interaction is not suitable for the operation habits of most domestic programmers.

Personal tip: Use this if you want to build a Swagger based document quickly and don’t require online debugging.

knife4j

Gitee address: gitee.com/xiaoym/knif…

Open source License: Apache-2.0 License

Star: 3k

Development language: Java, javascript

User: Unknown

★★★★ ★

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

Knife4j is an enhanced solution to generate Api documentation for Java MVC framework integration with Swagger. Formerly swagger-Bootstrap-UI, KNI4j was named for being as small, lightweight, and powerful as a dagger.

Advantages: Generate real-time online documents based on Swagger, support online debugging, global parameters, internationalization, access control, etc., very powerful.

Cons: The interface is a bit ugly and relies on extra JAR packages

Personal advice: If your company is not too UI demanding, you can use this document generation tool, the comparison function is quite powerful.

yapi

Github address: github.com/YMFE/yapi

Open source License: Apache-2.0 License

Star: 17.8 k

Development language: javascript

Users: Tencent, Alibaba, Baidu, JINGdong and other big companies

★★★★★ ★

Example address: yapi.fanruan.com/

Yapi is independently developed and open source by qunar’s front end team and mainly supports the following functions:

  • Visual Interface Management
  • The mock data
  • Automated interface testing
  • Data import (including Swagger, HAR, Postman, JSON, command line)
  • Rights management
  • Support local deployment
  • Support plugins
  • Support secondary development

Advantages: very powerful function, support authority management, online debugging, interface automation test, plug-in development, etc., BAT and other large factories in use, indicating that the function is very good.

Disadvantages: online debugging function requires plug-in installation, user health check is slightly bad, mainly to solve cross-domain problems, there may be security issues. However, to solve this problem, you can implement a plug-in yourself, should not be difficult.

Personal advice: This online documentation tool is very useful if you don’t care about the security of plug-in security. It is a magic tool, and I strongly recommend it.

apidoc

Github address: github.com/apidoc/apid…

Open source License: MIT License

Star: 8.7 k

Development language: javascript

User: Unknown

★★★★☆

Example Address: apidocjs.com/example/#ap…

Apidoc is a simple RESTful API document generation tool that extracts content in a specific format from code comments to generate documents. Support for most development languages such as Go, Java, C++, Rust, etc. You can use the apidoc lang command line to view the list of all supported languages.

Apidoc has the following characteristics:

  1. Cross-platform, Linux, Windows, macOS, etc.
  2. Support language wide, even if it is not supported, it is very easy to expand;
  3. Generate one document for multiple projects supporting multiple languages;
  4. The output template can be customized.
  5. Generate mock data from the document;

Advantages: Generate online documents based on code comments, less embedding of code, support multiple languages, cross-platform, and can also customize templates. Supports search and online debugging.

Disadvantages: you need to add specified annotations in the annotations. If the code parameters or types are modified, you need to modify the related content of annotations synchronously, which requires a certain amount of maintenance work.

Personal advice: This online document generation tool provides another way of thinking, Swagger is to add annotations to the code, while APidoc is to add data to the annotations, the code is less embedded, recommended use.

showdoc

Github address: github.com/star7th/sho…

Open-source license: Apache License

Star: 8.1 k

Development language: javascript, PHP

Users: over 10,000 + Internet teams are using it

★★★★☆

Example Address: www.showdoc.com.cn/demo?page_i…

ShowDoc is a great online document sharing tool for IT teams to speed up communication between teams.

What functions does it have:

  1. Responsive Web design that allows project documents to be shared to a computer or mobile device. You can also export the project to a Word file for offline viewing.
  2. Access management, ShowDoc has both public and private projects. Public projects can be accessed by any logged-in or non-logged-in user, while private projects require password authentication. The password is set by the project author.
  3. ShowDoc uses the Markdown editor, and the API template and data dictionary template can be easily inserted by clicking the button at the top of the editor.
  4. ShowDoc provides a historical version feature for your page, so you can easily restore the page to its previous version.
  5. Supports file import, including postman JSON files, Swagger JSON files, and ShowDoc Markdown compression packages. The system automatically identifies file types.

Advantages: support project authority management, a variety of format file import, full-text search and other functions, it is very convenient to use. And support both deployment of their own servers, but also support online hosting two ways.

Disadvantages: Does not support online debugging

Personal tip: This online documentation tool is worth using if you don’t require online debugging.

One last word (attention, don’t fuck me for nothing)

If this article is helpful to you, or inspired, help scan the QR code to pay attention to it, or like, forward, look at. In the public number reply: interview, code artifact, development manual, time management have super good fan welfare, in addition reply: add group, can communicate with many big factory elder and study.