portal
Making the address
Gitee address
Complete documentation
preface
【 Happy Touch fish 】 is an open source interface management tool based on Vue and Electron. The project was originally built to learn about Node.js and solve front-end coordination issues for the team. There are YApi, Rap2, Doclever, Nei, Swagger, Apidoc and other open source solutions in the community, as well as Postman, Eolinker, ApiPost and other commercial solutions.
Prior to this, the team tried community solutions such as YApi and Rap2, which were able to meet some of the basic requirements, but after further use, there were still some issues affecting efficiency. At that time, the biggest problem of using these two tools was that the interface could not support multi-level nesting, and the retrieval efficiency would be greatly reduced if some items had more interfaces. So I tried to write an interface management tool from scratch.
Team collaboration
A very core function. In the case of separation of front and back ends, a concise team management strategy will greatly improve the efficiency of division of labor. We classify permissions as read – only, read – write, and administrator.
- Read-only: Only users are allowed to view the document (typically you can assign this role to the front-end developer)
- Read and write: Allows you to add, delete, change, review, etc. (usually you can give this role to back-end developers)
- Administrator: In addition to reading and writing, users can be added or deleted
The three roles above meet most of your everyday needs. There are special cases where you may need more fine-grained permission control, such as when you want a user with read and write permission to edit the document, but not to export the entire document. We provide custom roles that are down to every interface and route (not normally needed).
Directory navigation
A very core feature, designing a convenient and easy to use directory navigation can greatly enhance the entry experience. We’ve summarized some common requirements from other open source project issues.
- Unlimited level nesting is supported
- Support for dragging and dropping files
- Support for dragging and dropping directories
- You can copy files individually or in batches
- One or multiple copy directories are supported
- Support for some right-click menus
- Batch delete
- The navigation bar interface must be expanded in linkage with the directory
The tool implements all of the above functions, but also extends some useful functions.
- Having more than 10 documents in a single directory reduces document retrieval efficiency. By default, the tool limits the number of documents in a single directory to eight, although it also allows you to customize the limit.
- With limited space for directory navigation, the tool allows you to use it
Ctrl + left mouse buttonTo view additional information about the node
Tabbed navigation
TAB navigation is for developers to quickly switch between multiple interfaces, open source products do not do this very well, we summarized these requirements in practice.
- The top navigation TAB should be linked with the left directory navigation
- Navigation tabs should allow drag and drop
- Navigation tabs require right mouse button operation
- Navigation tabs need to have dots to indicate when the document changes
- The navigation label needs to indicate the request type
Most of the commercial interface tools have the function of navigation tag, but most of the open source products do not have the function of navigation tag or the function completion is not high
Interface debugging (mock requests)
Most interface tools have built-in interface debugging capabilities, so developers only need to use one tool to complete interface debugging and interface entry. However, due to the restriction of the browser (the same origin policy), it is highly likely that an HTTP request will fail to be initiated directly on the Web. Some common solutions are listed here.
| plan | disadvantages |
|---|---|
| Browser plug-in | Plug-in installation and Cookie support are not high |
| Remote server proxy forwarding | An internal network segment such as 192.168.0.0 cannot be accessed |
| Using the Client (Electron) | The client needs to be installed |
Technically, it is a good practice to use the client to circumvent the same-origin policy, and the powerful API of the client can accomplish many things that cannot be accomplished on the Web. Of course, installing the client can also bring some inconvenience to users. At present, most of the mainstream commercial projects use the client side to provide interface debugging function for users, and some tools do not even provide the Use of the Web side. We use the client-side approach to implement interface debugging, but also retain the use of the Web side function, except interface debugging and Mock functions can not be used, there is no other difference between the Web side and the client side function. In the future, we will also provide browser plugins so that users can use interface debugging on the Web side
We summarize some common interface debugging requirements
- Supports common GET, POST, PUT, DELETE, OPTIONS, and PATCH
- RESTFUL query parameters are supported
- Support x-www-form-urlencoded, multipart/form-data, JSON, XML, binary and other common MIME types
- Multipart /form-data supports file passing
- Supports custom headers
- Support sending cookies
- Support for custom variables
- Supports formatted preview return values, JSON, text/ HTML, image and other types
Pre operation, post operationwebsocket
The interface type
Adding, deleting, modifying and checking the interface is the core part of the whole interface tool. Common open source products have weak support for request parameters (Body) and multiple return parameters. We concluded that in a typical business scenario, interface entry should include the following core modules.
- Request method and request URL entry
- Interface label Entry
- Request Parameters (Params)
/api/demo? id=3&name=lee - Request Parameters (Path)
/api/demo/{id} - Request Parameters (Body)
- none
- Form-data (can upload files)
- X-www-form-urlencoded (Form submission method)
- application/json
- Text /plain, text/plain, Application /javascript, application/ XML and other MIME types
- binary
- Request header
- Return parameters (typically you can add more than one return parameter)
- Remarks (rich text format)
- The draft state
- Variable support
- Supports multiple parameter types: Number, Integer, String, Array, Object, File, Binary, Boolean,
Null,Enum
The purpose of the interface tool is to format certain types of data, which are transmitted through the HTTP body. The application uses the content-Type in the header to distinguish the data format.
In addition to perfecting the necessary interface modules, the tool also thinks a lot about input efficiency. We sorted out users’ common input requirements from open source project issues such as Yapi and Rap2.
- The input of each field is expected to have a completion function
- Parameter Template Function
- Json data can be imported and remarks can be automatically completed
- When you send a mock request, you want the real return value to be applied to the document
The import function
At present, there are many kinds of interface tools on the market. There are several main problems when dealing with import.
- Most interface tools do not have strict data format definitions
- The current system data interface is not compatible with the third-party interface
- Some tools do not provide the ability to export data in a processable format (JSON, YAML, etc.)
- Specifications like OpenAPI/Swagger are very detailed and require a lot of logic to handle
- For openAPI/Swagger specifications, users fail to write in strict accordance with the specifications, resulting in import errors
- There are some additional configuration requirements for importing data (e.g., specify where to export, specify how much data to export, etc.)
The most stable and generally accepted specification is the OpenAPI specification, which is supported by many commercial tools. Tools like Postman have a very large market share, and most tools support this type of data import. We collected some common interface tools and listed their support for imports.
| The document type | support | note |
|---|---|---|
| Openapi/Swagger | Supports a single file, 3.0 or later, is compatible with common syntax rules, and provides long-term support | The OpenPAI specification has very rich implementation details, and the tool will evolve and be compliant with this specification over the long term. Multiple file import support will be provided in the future |
| postman | Supports version 2.1 or later, compatible with common syntax rules, and provides long-term support | |
| Yapi | Supports import and compatibility with common syntax rules | Interface tools well known in the open source community, unfortunately no longer maintained, we provide migration support |
| Rap2 | Temporary does not support | Ready to support |
| ShowDoc | Temporary does not support | |
| Nei | Temporary does not support | |
| Docway | Temporary does not support | |
| ApiPost | Temporary does not support | |
| Eolinker | Temporary does not support | Ready to support |
On top of the general import requirements, we extended some functions to improve the efficiency of some in-project migration.
- Allows multiple projects to export data to each other
- Allows users to specify the mount directory for import
Export function
On the one hand, the export function facilitates users to share documents with third-party users, and on the other hand, provides migration and backup capabilities. Here are some common export scenarios
| Export format | Whether to support | note |
|---|---|---|
| JSON(Fish format) | support | Happy fishing. Json |
| Export standard interface data for backup or migration to other interface tools | ||
| Support specific content export | ||
| HTML | support | Happy fishing. HTML |
| Provides very complete preview function support | ||
| Support specific content export | ||
| Markdown | Temporary does not support | Ready to support |
| Temporary does not support | Ready to support | |
| Word | Support co., LTD. | Based on theofficegen |
| The directory generation function is missing | ||
| Ugly style | ||
| OpenApi | Temporary does not support | Ready to support |
| Openapi’s rich toolchain is available | ||
| Generating online links | support | Online link (Password: 111111) |
| Support specific content export | ||
| This can be very useful when sharing third parties |
Because HTML has such good UI presentation capabilities, we put a lot of effort into static HTML. We recommend using HTML as the preferred offline document.
Recycle bin and log function
The logging function is an important part of team management and security operations, and the tool keeps a detailed record of every step of the interface operation.
- Deleting a single document
- Deleting a Directory
- Deleting Nodes in Batches
- Edit the document
- New document
- New Folder
- Copy the document
- Make a copy of the document
- Change document location
- rename
- Import and export
- Permission to change
In addition to the basic records, the tool also provides very rich retrieval. For certain operations, users may want to obtain more detailed log information. For example, when editing a document, users may want to know exactly what was changed. The tool currently has limited support in this area and will continue to improve this area in the future.
The tool distinguishes two states: interface input and interface preview. The purpose of interface input is to achieve efficient input, while the purpose of interface preview is to achieve efficient retrieval. Unlike other tools that export data, there are some optimizations for retrieval and preview.
In the actual project development, joint investigators are more concerned about the latest several pieces of data modified by someone, and data retrieval can be very efficient through filtering conditions.
As opposed to a tabular JSON presentation, the following rendering is more developer-friendly.
A Mock function
You can use Mock functionality for rapid development, and like most interface tools we support itMock.jsSyntax, and we simplify the whole mock process without you having to do any extra configuration. The tool launches a Mock server locally, which you can simply use as a backend server.
Restricted by the browser, only clients can start the Mock server
Automated testing
Unfortunately, this is not currently supported, but we are already working on this very important feature.
Secondary development & deployment
Client technology stack
- Vue
- ElementUI
- Electron
Server technology stack
- Egg.js
- MongoDB
At present, most of the open source interface tools only provide use and deployment documents, secondary development will be more difficult for users. In order to extend the life of the project and attract more developers to participate, we made improving the development documentation and product design ideas one of the most important development tasks. Due to the complexity of the project itself, the perfect development documents will occupy a lot of opening time, and the documents will have a certain lag.
Due to the limitations of personal technical ability, the code can not do very elegant, but the attitude is still correct, the annotations will be very serious to write!
Product Design Idea
Development of the document
Deployment document
conclusion
We want to give users who are looking for an interface management tool a choice, and we are also improving our product design and development documentation to get more people involved in the project.