portal
Gitee address full documentation
preface
【 Happy Fish 】 is an open source interface management tool based on Vue and Electron. The project was originally built to learn about Node.js and to solve the team’s front-end coordination issues. There are open source solutions such as YAPI, Rap2, DoClever, NEI, Swagger, ApiDoc, and commercial solutions such as Postman, Eolinker, and ApiPost.
The team had tried community solutions like YAPI and Rap2, which met some basic requirements, but after further use, there were still some problems with 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 there were more interfaces for some items. I tried to write an interface management tool from scratch.
Team collaboration
A very core function, in the case of front and rear end separation, a set of 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 allow the user to view the document (you can typically assign this role to front-end developers)
- Read/write: Allows documents to be added, deleted, modified, searched, etc. (This role is usually given to back-end developers)
- Administrator: You can add or delete users in addition to reading and writing
The three roles above can meet most of your daily usage needs. In some cases you may need more granular access control, such as for a user who has read and write permissions you only want to be able to edit documents, but you don’t want to be able to export all documents. We provide custom roles that are accurate to every interface and route (not normally needed).
[Rights Management]
Directory navigation
A very core function, design a convenient and easy to use directory navigation can greatly enhance the input experience. We’ve summarized some common requirements from other open source project issues.
- Support for unlimited level nesting
- Support drag and drop files
- Support drag and drop directories
- Support single or batch copy of files
- Support for single or multiple copy directories
- Support some right – click menus
- Able to delete in batches
- The navigation bar interface should be expanded in conjunction with the directory
The tool implements all of the above functions, while extending some of the practical functions.
- Having more than 10 documents in a single directory slows down document retrieval. By default, the tool limits the number of documents in a single directory to 8, although you can customize the limit.
- Because directory navigation space is limited, the tool allows you to use it
Ctrl + left mouse buttonTo view additional information about the node
[Batch delete node]
Batch document copy and paste
Tabbed navigation
Tab navigation is designed to make it easy for developers to quickly switch between multiple interfaces. The open source product is not very good at this, and we have summarized these requirements in practice.
- The top navigation TAB is linked to the left directory navigation
- Navigation labels should allow drag and drop
- Navigation tabs require the right mouse button to operate
- The navigation TAB should have a dot when the document changes
- The navigation label needs to mark the request type
Most commercial interface tools have the function of navigation tag, but most open source products do not have the function of navigation tag or the functional completion is not high
【 Navigation bar related operations 】
Interface debugging (mock requests)
Most interface tools come with built-in interface debugging, so that developers can debug and enter interfaces with only one tool. However, due to the limitations of the browser itself (the same origin policy), making an HTTP request directly on the Web side is likely to fail. Some common solutions are listed here.
| plan | disadvantages |
|---|---|
| Browser plugin | Plug-in installation, Cookie support is not high |
| Remote server proxy forwarding | Intranet segments 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 avoid the same origin policy. At the same time, relying on the powerful API of the client, it can also accomplish a lot of things that the web side cannot do. Of course, the installation of the client will also bring some inconvenience to users. At present, most mainstream commercial projects provide interface debugging function for users in the form of client, and some tools even do not provide the use of Web side. We use the client-side approach to implement interface debugging, while retaining the use of the Web side functions, except that interface debugging and Mock functions cannot be used, there is no other functional difference between the Web side and the client side. We will also provide browser plugins in the future so that users can debug the interface on the web side
Let’s summarize some common interface debugging requirements
- Support common GET, POST, PUT, DELETE, OPTIONS, PATCH
- Support for RESTful type query parameters
- Supports x-www-form-urlencoded, multipart/form-data, JSON, XML, binary and other common MIME types
- Multipart /form-data supports passing files
- Support for custom headers
- Support for sending cookies
- Support for custom variables
- Support formatted preview return values, JSON, text/ HTML, image and other types
Preposition operation, post operationwebsocket
[Non-JSON formatted data return display]
[JSON type returns data display]
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 the request parameter (Body) and multiple return parameters. We concluded that in a typical business scenario, interface entry should contain the following core modules.
- Request method and request URL entry
- Interface label entry
- Request parameters (Params)
/api/demo? id=3&name=lee - Request parameter (PATH)
/api/demo/{id} -
Request parameter (Body)
- none
- Form-data (you can transfer files)
- X-www-form-urlencoded (form submission)
- application/json
- Text /plain, Text /plain, Application/JavaScript, Application/XML and other MIME types
- binary
- Request header
- Return parameters (you can usually add multiple return parameters)
- Remarks information (rich text format)
- The draft state
- Variable support
-
Supports rich parameter types: Number, Integer, String, Array, Object, File, Binary, Boolean, NULL, Enum
The interface tool distinguishes the body input mode. The purpose is to format some specific types of data, which are transmitted through the HTTP body. The program distinguishes the data format by the Content-Type in the header.
[Interface entry workspace]
In addition to improving the necessary interface module, the tool also in the input efficiency of a lot of ways. We sorted out common input requirements of users from open source project issues such as YAPI and Rap2.
- Each field entry is expected to have a completion function
- Parameter template function
- JSON type data import function, and can automatically complete remarks
- When you send a mock request, you want to be able to apply the real return value to the document
[Quick completion of fields]
[Parameter template]
[JSON data import]
[return parameters applied to the document]
The import function
At present, there are many kinds of interface tools in 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 well compatible with third-party interfaces
- Some tools do not provide export capabilities for data in a processable format (JSON, YAML, etc.)
- Specifications such as OpenAPI/Swagger are very detailed and require a lot of logic to be processed
- A specification like OpenAPI/Swagger, where the user fails to follow the specification to the letter, causes an import error
- There are some additional configuration requirements for importing data (eg: specify where to export, specify how much data to export, etc.)
The most stable and widely 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’ve collected some of the most commonly used interface tools and listed their support for imports.
| The document type | support | note |
|---|---|---|
| Openapi/Swagger | Support single file, support 3.0 and above, compatible with common syntax rules, provide long-term support | The OpenPAI specification has very rich implementation details, and the tool will be refined and compatible with the specification over the long term and will provide support for multiple file imports in the future |
| postman | Support version 2.1 and above, compatible with common syntax rules, provide long-term support | |
| Yapi | Support for import, compatible with common syntax rules | A well-known interface tool 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 intra-project migration.
- Allows multiple projects to export data to each other
- Allows the user to specify the mount directory when importing
[Import each other within the project]
[Extra imported data configuration]
Export function
On the one hand, the export function is convenient for users to share documents with third-party users, and on the other hand, it also provides some migration and backup capabilities. Here are some common export scenarios
| Export format | Whether to support | note |
|---|---|---|
| JSON(fish format) | support | Happy fish. JSONProvide standard interface data export, convenient for users to backup or migrate to other interface tools, support specified content export |
| HTML | support | Happy fishing. HTMLProvides a very complete preview function support, support for specified 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, the style is ugly |
| OpenApi | Temporary does not support | Ready to support |
| OpenAPI’s rich toolchain is available | ||
| Generate online links | support | Online link (Password: 111111)Support for export of specified content, which can be useful when sharing with third parties |
Since HTML has a very good UI presentation capability, we spent a lot of effort on static HTML. We recommend using HTML as your preferred offline document.
[Export on Demand]
Recycle bin and log function
Logging is a very important part of team management and secure operations, and the tool keeps detailed records of every step of the interface.
- Delete a single document
- Delete a single directory
- Batch Delete Nodes
- Edit the document
- New document
- New folder
- Copy the document
- Make a copy of the document
- Change the document location
- rename
- Import and export
- Permission to change
In addition to the basic records, the tool also provides a very rich search. For some actions the user may want to get more detailed log information, for example, for editing documents, the user may want to know exactly what has changed. The tools currently have limited support in this area and will continue to improve this area in the future.
[Log function]
[Recycle station function]
Interface to preview
The tool distinguishes two states: interface entry and interface preview. The purpose of interface entry is to achieve efficient entry, while the purpose of interface preview is to achieve efficient retrieval. Unlike other tools that export data, the tools have some optimizations for retrieval and preview.
In the actual project development, the coordinators are more concerned about the recent several pieces of data modified by so-and-so, and the data retrieval can be carried out very efficiently through filtering conditions.
[Support rich filtering conditions]
As opposed to a tabular JSON presentation, the following rendering is very developer-friendly.
[JSON presentation with comments]
[Interface Preview Interface]
A Mock function
You can use the Mock feature for rapid development, and like most interface tools we support itMock.jsSyntax, and we simplify the mocking process without any extra configuration. The tool starts a Mock server locally, which you can simply use as a back-end server.
Subject to browser restrictions, only clients can start the Mock server
Automated testing
Unfortunately, this feature is not currently supported, but we are 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 interface tools of open source classes only provide documents for use and deployment, and secondary development will be more difficult for users. In order to extend the life of the project and attract more developers, we made it one of the most important development tasks to improve the development documentation and product design ideas. Due to the complexity of the project itself, complete development documents will occupy a lot of open time, and the documents will have a certain lag.
Due to the limitation of personal technical ability, the code can not be done very elegant, but the attitude is still correct, some annotations will be very serious to write!
[Note information with the right attitude]
Product Design Ideas
Development of the document
Deployment document
conclusion
We want to offer more options to users who are looking for interface management tools, as well as improve product design and development documentation, hoping to attract more people to participate in the project.