Interface documentation is used throughout project development testing. Front-end and back-end development needs to define and document interfaces in the early stage of development. QA also needs to rely on these interface documents to test functions and interface tests. Interface documents tend to exist in the simplest static form. However, in the intense agile development model, many interfaces change or become obsolete as version iterations occur, and development rarely updates such static documentation at a later stage. Reading “out of date” interface documentation can be a pain for QA staff, and the cost of communicating with development goes up, not down. These static documents, which are not easy to maintain in time, will eventually go unattended over time. Therefore, we wanted to find a long term maintainable, lightweight and convenient interface documentation tool.

Postman Postman is a popular Chrome plugin for web page debugging, which is often used for temporary HTTP request debugging. Fortunately, Postman can save debugged requests to the Collection. The resulting Collection can be used as a simple and effective interface document that supports online testing and can be shared and synchronized by logging in with the same account. For QA, interface testing with Postman is the same thing as interface documentation, testing is documentation, and maintenance costs are low.

Swagger “Swagger is a canonical and complete framework for generating, describing, invoking, and visualizing RESTful style Web services.” In short, Swagger is a powerful interface management tool and provides a front-end separation solution for multiple programming languages. Swagger mainly contains the following four parts:

  1. Swagger can be embedded directly into a project, automatically generating interface documentation by writing comments at development time;
  2. Swagger contains SwaggerEditor, which is an editor using yamL language SwaggerAPI, and supports the export of YAML and JSON interface files.
  3. Swagger contains SwaggerUI, which displays the interface document compiled by SwaggerEditor in HTML form.
  4. Swagger supports exporting server or client code in a variety of languages based on defined interfaces. 1 and 4 are more development-oriented, where the development team has the need to automatically generate documentation and follow the front and back end separation in development and self-testing. However, 2 and 3 are relatively independent interface document management solutions for reference by QA staff, which are also the main part of our attention. Swagger Provides an online demo of Swagger Editor and Swagger UI, as shown below. It can be seen that Swagger can completely define the content of an interface, including the specific structure and type of each parameter, return value. Swagger Editor can be edited in real time and debugged online. The edited API can be exported as JSON file, which can be opened with Swagger UI to see a more beautiful interface document.

Local deployment of Swagger Editor and SwaggerUI is simple, as both can be downloaded directly from Github, deployed to a local Tomcat server, and accessed via a browser. Other deployment modes are also provided. The detailed steps are described in the help documents. RAP RAP is a complete set of visual interface management tools of Ali, which can define the interface structure, dynamically generate simulation data, and verify the correctness of real interfaces. More than that, RAP provides a range of services around interface definition, including team management, project management, document versioning, mock plug-ins, and more. The RAP website provides a very detailed wiki and video tutorials on how to use RAP. Unlike Swagger, which needs to be written in a markup language, RAP can completely visually define project-related information, define interface request responses, and so on, with low learning costs. RAP also provides backend developers with interface validation capabilities, front-end developers with mock data tools, and more.

DOClever

DOClever is a visual interface management tool that analyzes interface structures, validates interface correctness, and improves collaboration with a range of automated tools around interface definition documents. DOClever used javascript as a development language, front-end is vUE + Element UI, back-end is Express +mongodb, such a framework integrated with the characteristics of high concurrency, fast iteration, ensure the stability and reliability of the system.

DOClever products have the following features:

Can edit the interface information management, support the get, post, put, delete, patch five kinds of methods, support HTTPS and the HTTPS protocol, and query support, body, json, raw, rest, the parameters of the formdata visual editing. Json can also be visually edited at an infinite level. Status codes, code injection, Markdown documentation, and more.

• Interface debugging run, you can encrypt the parameters, from MD5 to AES, return parameters and model real-time analysis comparison, give inconsistent places, find out the possible problems of the interface. If you don’t want to document by hand, try the interface’s data generation feature, which generates document information from the data that the interface runs with one click.

• Seamless integration of mocks. DOClever is itself a mock server. When you set the development state of your interface to finished, local mocks automatically request real interface data, otherwise they return predefined mock data.

• Support postman, rap, Swagger import, convenient for you to do seamless migration, but also support HTML file export, convenient for you to browse offline!

Project snapshot versions and interface function in parallel, you can for a project definition 1.0, 1.1, 1.2, and can freely switch between different versions of rolled back, no longer afraid of interface information loss of the interface has a snapshot function at the same time, when you interface development by half or interface requirements change, can check before editing interface information at any time.

• Automated test function. Currently, most of the interface automated tests of similar platforms in the market are pseudo-automated, unable to deal with a complex scenario, such as obtaining verification code, logging in, obtaining order list, obtaining details of a particular order, and a series of context-related operations. DOClever’s automated testing allows you to do this on a web page with minimal javascript code, and it also allows you to batch execute test cases in the background and send the results to your team. You can get the status of the interface in real time.

• Team collaboration. Many of these platforms charge for it, but DOClever thinks good things need to be shared. You can create a team, bring people into groups, assign them related projects and permissions, make team announcements, etc.

DOClever is open source and free, supports Intranet deployment, many companies consider the security of data, do not want to put the interface on the public network, it does not matter, DOClever gives a convenient and quick solution, you can put the platform on their own Intranet, do not need to connect to the Internet, at the same time also a lot of features, Even for product upgrades, DOClever offers easy upgrades!

Doclever. cn Github: github.com/sx1989827/D… Yards cloud: git.oschina.net/sx1989827/S… Documents: doclever. Cn/help/help. H… QQ group: 611940610

Postman is a test oriented API widget that can maintain a “test record” very lightly, suitable for small test teams to use and maintain on their own. Swagger’s rich and independent functions enable it to be applied to a variety of requirements, both development and testing can use this tool to optimize their own development process, interface documentation maintenance, interface testing, etc. However, the learning and access cost of Swagger is relatively high, which requires in-depth cooperation between development and testing. RAP application scope is very clear, is a tool platform for developers to self-test and joint commissioning, it is more suitable for development as the core of the interface maintenance, but at present basically not maintenance. DOClever is a powerful platform with high praise rate in China, and the product is completely free and open source, which can be deployed offline; At the same time, the product is updated and iterated frequently, so they are also doing this product by heart.

The above is for testers’ reference only.