table of Contents
Interface specification document management practices contribute to increasing components work together: development efficiency (such as front and rear end of the separation), for the interface description of the global project management perspective, and can be easily achieved even released.
Improve document management and document format should contain two parts of the document management, as an explanation.
API documentation format
The API specification document format helps to understand, can greatly improve development efficiency, reduce unnecessary communication costs.
However, not need to adopt a unified format constraints (after all unreasonable requirements of different projects, different architects have different styles), some people like written in Word, some people have chosen hobby Markdown syntax. In short, regardless of the format employed, the API interface must be full, clear description (eg: interface function, method definitions, the meaning of the parameters, formats, and so returned).
If the team has no uniform API documentation format specification, reference may ants gold dress Document Format API demonstration design.
Document management
RESTFul API documentation management (generation, maintenance) can be roughly divided into three categories:
Annotation-based implementation, code and documentation together
Based on the benefits of annotation document is generated code and documentation together, not alone maintain a document; shortcomings are obvious, the document notes the need to embed the code in the business, it will make the code look very messy.
Typical implement document management tool based on annotation methods are: Swagger, Api2Doc.
Swagger
Swagger is a very popular RESTFul document generation tool, but if you need to generate a relatively standardized and complete documentation, to write too many notes, it is cumbersome, see: https://swagger.io/ .
Swagger on the use of the interface to achieve document management can refer to the following resources:
https://github.com/swagger-api Swagger GitHub project's official website
https://www.jianshu.com/p/33c28a65deb8 Swagger- powerful API documentation tool
https : //blog.csdn.net/zhangxin09/article/details/82699353 Swagger 2 (Open API V3.0) to generate the Java documentation guidelines (on)
https://www.ibm.com/developerworks/cn/java/j- using-swagger-in-a- spring-boot-project / index.html use Swagger document in Spring Boot project
https://blog.csdn.net/u014745069/article/details/80246803 Swagger use interface parameters ---- annotated using the defect
https://blog.csdn.net/xiaojin21cen/article/details/78654652 swagger2 explanatory notes
https://blog.csdn.net/cy921107/article/details/82761575 Swagger2 on JSONObject parameters show detailed parameters and parameters described in the API documentation
http://www.voidcn.com/article/p-bxgydblc-bnz.html how to use Swagger eliminate barriers separating the front and rear end?
https://www.cnblogs.com/softidea/p/6226463.html Swagger topic
https://www.cnblogs.com/ceshi2016/p/10511959.html Swagger Annotation Comments (recommended collection)
Api2Doc
Api2Doc principle similar to Swagger, but based on Spring Boot framework.
Currently the tool is not perfect, being given integrated 1.0.2 version, see:
https://github.com/terran4j/commons/tree/master/commons-api2doc api2doc official website
API-based test generation tool
Separation of code and documentation, but without writing a separate document, the document can be generated at the interface testing.
Postman
Postman to support publishers' request for the API documentation can be viewed online, if you need to consider privacy rights and may not be suitable.
http://book.crifan.com/books/api_tool_postman/website/postman_api_doc/preview_publish_api_doc.html preview and publish API documentation
rest-client
rest-client personal REST API testing tool similar to the postman's open source API documentation can be generated directly off according to API, written in Java Swing-based GUI interface.
https://github.com/Wisdom-Projects/rest-client
Independent writing documentation
Independent maintenance API documentation is the easiest way, but the disadvantages are also obvious, and that is probably not in time synchronization code and documentation, and it might even cause the document is outdated.
You can use whatever you like to write a separate API documentation format, can be designed according to the needs of online (currently there is no lack many online API Management System) or offline: format (for example, you can use Execel table, MarkDown syntax for writing, and even Word) of.
Here are several popular Web-based API management tools were brief:
RAP
Official website: https://github.com/thx/RAP
RAP Ali open source Web interface management tool, open source, free, support automation interfaces, MOCK data generation, test automation, enterprise-class management.
While the RAP feature comparison, but does not support the request parameters in JSON format, bad review.
DOClever
DOCleven API is a business management system, the official website: http://doclever.cn/controller/index/index.html .
There are open source version, see: https://github.com/sx1989827/DOClever .
Although DOClever known as very powerful and comprehensive, but it is the open source version of the cut was too brief, not suitable to take over the direct use, based on secondary development can do it.
When installation is recommended not to use the open source version of npm install, various error when you start using the source installation do not have this problem.
# 在安装DOClever之前先安装并启动MongoDB
# 使用源码方式安装DOClevere
$ git clone https://github.com/sx1989827/DOClever.git
$ cd DOClevere
$ npm startIf the startup error, it is recommended to use node version 8.11.1.
APIDOC
Another tool for independently created API documentation is APIDOC, the official website: http://apidocjs.com .
With respect to the common interface document management tools, APIDOC taking a clear comparison of odd way. It is through the interface (Note: This interface is not a business interface, but is intended to interface generation document) define API, is essentially maintenance interface documents outside business code.
https://blog.csdn.net/soslinken/article/details/50468896 use apidoc generate Restful web Api document
https://blog.csdn.net/qq_27384769/article/details/78622831 apidoc Tutorial - write nice api documentation
CrapApi
CrapApi is open source products is the most satisfactory, and basic document management API is more comprehensive, but for support MOCK test is still relatively weak.
But the pros and cons, for an open source system, the core functionality has been pretty good, recommended, see: https://gitee.com/CrapApi/CrapApi .
CrapApi installation is very simple, which itself is a traditional Java Web projects, final packaging format war file, so you can access just to war package into the Tomcat webapps directory.
It is worth noting: Because CrapApi source code of SQL scripts are derived using the tool, which notes (mainly in the format /***/of a comment) in some SQL tool may be error, just delete it.
Written in the last
API for document management a variety of ways, but certainly not a program that is perfect, each has its own strengths and weaknesses, mainly in:
1. maintain documents in code, it can be done through annotations in Java, most conducive to maintaining the consistency of code and documentation, but in order to generate a relatively well documented need to add a bunch of notes, which will pollute the simplicity of true business code, maybe even defective performance loss;
2. separate written document Although not pollute the way business code, but due to the complete separation of code and documentation, will be invisible to increase the cost of maintaining the consistency of code and documentation;
3. in contrast, document generation based API testing tool way more eclectic, but the resulting features and tools of the document itself bind very tightly, it is difficult to deploy privatization and rights management.
Indeed, Either way, the maintenance of the document requires some hard and fast rules and regulations to ensure the timely update. "Programmers do not like to write the document, but want someone else to write the document," which is a common problem for developers, even with maintenance documentation in the code: the way (such as Swagger), if the developer bad habits or not prescribed mandatory developers timely maintenance updates a document, the document still does not solve the problem with the code synchronization, after all, this is the need for people to drive (increase changing parameters, the method also need to inject corresponding document notes).
So, for the maintenance of the API documentation is no universal solution, regardless of the document using maintenance mode must have a corresponding system of enforcement, or even the best tool to use is still not a bad sense. As for the choice of what kind of document management, depending on the architect's preferences, or according to the actual needs of the project itself (such as: the need for external release and other factors) to select the appropriate program can be, after all, no matter what means are just a tool to achieve their goals, the key is how to efficiently use.
[Reference]
https://www.jianshu.com/p/be32a38f408d API interface management of the Road
https://blog.csdn.net/vimx86/article/details/78381838 interface document management solutions
https://hacpai.com/ Article This article was / 1519833837647 the API and management tools Swagger RAP comparison
https://www.cnblogs.com/minsons/p/7133095.html of Api management tool (spring-rest-docs)