Document management tool based on Vue and Electron open source interface

Document management tool based on Vue and Electron open source interface

Portal

GitHub address

Gitee address

Full documentation

Preface

[Happy Fishing] is an open source interface management tool based on Vue and Electron. When this project was originally built, it was to learn Node.js and solve the team's front-end and back-end coordination problems. In the community, there are open source solutions such as YApi, Rap2, Doclever, Nei, Swagger, Apidoc, and commercial solutions such as Postman, Eolinker, and ApiPost.

Prior to this, the team tried community solutions such as YApi and Rap2. They were able to meet some basic needs, but after in-depth use, there were still some problems affecting efficiency. The biggest problem with using these two tools at that time was that the interface could not support multi-level nesting, and some projects with more interfaces would greatly reduce the retrieval efficiency. So I tried to write an interface management tool from scratch.

team cooperation

A very core function, in the case of separation of front and back ends, a set of concise team management strategies will greatly improve the efficiency of division of labor. We divide permissions into three categories: read-only, read-write, and administrator.

  • Read-only: Only allow users to view documents (generally, front-end developers can be given this role)
  • Reading and writing: Allows adding, deleting, modifying, and checking documents, etc. (Generally, back-end developers can be given this role)
  • Administrator: In addition to reading and writing, you can also add or delete users

The above three roles can meet most of the daily use needs. In some special cases, you may need more fine-grained permission control. For example, you only want a user with read and write permissions to edit documents, but you don't want him to export all documents. We provide a custom role function, which can be accurate to each interface and route (usually not used under normal circumstances).

authority management

Directory navigation

A very core function, designing a convenient and easy-to-use directory navigation can greatly enhance the entry experience. We have summarized some common requirements from other open source project issues.

  • Support unlimited levels of nesting
  • Support drag and drop files
  • Support drag and drop directory
  • Support single or batch copy files
  • Support single or multiple copy directories
  • Support some right-click menus
  • Ability to delete in bulk
  • The navigation bar interface should be expanded in conjunction with the directory

The tool realizes all the above functions, while also expanding some practical functions.

  • Having more than 10 documents in a single directory will reduce the efficiency of document retrieval. By default, the tool limits the existence of only 8 documents in a single directory. Of course, it also allows you to customize the limit.
  • Due to the limited space for directory navigation, the tool allows you to use
    Ctrl + left mouse button
    To view additional information about the node

[Delete nodes in batches]

Batch Document Copy and Paste

Tab navigation

Tab navigation is to facilitate developers to quickly switch between multiple interfaces. The open source product is not very complete. We have summarized these requirements in practice.

  • The top navigation label should be linked with the left directory navigation
  • Navigation tabs should allow drag and drop
  • Navigation tab requires right mouse button operation
  • When the document changes, the navigation label needs to have a small dot prompt
  • The navigation label needs to indicate the request type

Most of the commercial interface tools have the navigation label function, but most of the open source products do not have the label navigation function or the function completion is not high

Navigation bar related operations

Interface debugging (simulation request)

Most interface tools have built-in interface debugging functions, so that developers only need to use one tool to complete interface debugging and interface entry. However, due to the limitation of the browser itself (same-origin policy), directly initiating HTTP requests on the web side will likely fail. Here are some common solutions.

ProgramDisadvantage
Browser plug-inPlug-in installation, cookie support is not high
Remote server proxy forwardingIntranet segment like 192.168.0.0 cannot be accessed
Use client (Electron)Need to install the client

Technically speaking, it is a good practice to use the client to circumvent the same-origin policy. At the same time, relying on the powerful API of the client can accomplish many things that cannot be done on the web. Of course, installing the client will also bring some to the user. inconvenient. At present, most mainstream commercial projects adopt the form of client to provide users with interface debugging functions, and some tools do not even provide web-side use. We use the client-side approach to implement interface debugging, while also retaining the use of the web side. Except for interface debugging and mock functions cannot be used, there is no other difference in functionality between the web side and the client side. We will also provide browser plug-in functions in the future, so that users can use the interface debugging function on the web side

We summarize some common interface debugging requirements

  • Support common GET, POST, PUT, DELETE, OPTIONS, PATCH
  • Support RESTFUL type query parameters
  • Support x-www-form-urlencoded, multipart/form-data, json, xml, binary and other common MIME types
  • multipart/form-data supports transferring files
  • Support custom header
  • Support sending cookies
  • Support custom variables
  • Support formatted preview return value, json, text/html, image and other types
  • Pre-operation, post-operation
  • websocket

[Return display of data in non-JSON format]

[Json type return data display]

Interface entry

Adding, deleting, modifying and checking interfaces is the core part of the entire 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 parameter (Path)
    /api/demo/{id}
  • Request parameters (Body)
    • none
    • form-data (files can be transferred)
    • x-www-form-urlencoded (form submission method)
    • application/json
    • MIME types such as text/plain, text/plain, application/javascript, application/xml, etc.
    • binary
  • Request header
  • Return parameters (usually you can add multiple return parameters)
  • Remarks information (rich text format)
  • Draft status
  • Variable support
  • Support rich parameter types Number, Integer, String, Array, Object, File, Binary, Boolean,Null,Enum

The interface tool distinguishes the body entry method, and the purpose is to format certain specific types of data. These data are transmitted through the HTTP body, and the program distinguishes the data format through the Content-Type in the header.

Interface entry work area

In addition to perfecting the necessary interface modules, the tool also thought of a lot of methods in terms of input efficiency. We sort out the common input requirements of users from open source project issues such as Yapi and Rap2.

  • The entry of each field hopes to have a completion function
  • Parameter template function
  • json type data import function, and can automatically complete remarks
  • When sending a simulation request, I hope to apply the real return value to the document

[Field quick completion]

Parameter template

[Json data import]

[Return parameters applied to the document]

Import function

At present, there are many types of interface tools on the market, and there will be the following main problems when processing import.

  • Most interface tools do not have strict data format definitions
  • The current system data interface is not very compatible with third-party interfaces
  • Some tools do not provide the export function of processing format data (JSON, YAML, etc.)
  • The specification details such as openapi/swagger are very rich and require a lot of logic to be processed
  • For specifications such as openapi/swagger, users fail to write in strict accordance with the specifications, resulting in import errors
  • Importing data will have some additional configuration requirements (eg: specify the export location, specify the amount of exported data, etc.)

At present, the relatively stable and widely recognized specification is the OpenAPI specification, and many commercial tools support this specification. Tools such as postman have a very large market share, and most tools also support this type of data import. We have collected some commonly used interface tools, and listed the tool's support for import.

Document typeSupportRemarks
Openapi/SwaggerSupport single file, support version 3.0 and above, compatible with common syntax rules, provide long-term supportThe openpai specification has very rich implementation details, and the tool will be perfect and compatible with this specification for a long time. Multi-file import support will be provided in the future
postmanSupport 2.1 and above, compatible with common syntax rules, provide long-term support
YapiSupport import, compatible with common syntax rulesA very well-known interface tool in the open source community. Unfortunately, it is no longer maintained. We provide migration support
Rap2Not currently supportedReady to support
ShowDocNot currently supported
NeiNot currently supported
DocwayNot currently supported
ApiPostNot currently supported
EolinkerNot currently supportedReady to support

On the regular import requirements, we have expanded some functions to improve the migration efficiency of some projects.

  • Allow multiple projects to export data to each other
  • Allow users to specify the directory to be mounted when importing

[Mutual import within the project]

[Additional import 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 certain migration and backup capabilities. Here are some common export scenarios

Export formatDoes it supportRemarks
JSON (fishing format)stand byHappy fishing.json
Provide standard interface data export, convenient for users to backup or migrate to other interface tools
Support specified content export
HTMLstand byHappy Fishing.html
Provide very complete preview function support
Support specified content export
MarkdownNot currently supportedReady to support
PDFNot currently supportedReady to support
WordLimited supportBased on officegen
Catalog generation function is missing
Ugly style
OpenApiNot currently supportedReady to support
You can use openapi's rich tool chain
Generate online linkstand byOnline link (password: 111111)
Support specified content export
It will be very useful when sharing with a third party

Because HTML has very good UI performance capabilities, we spent a lot of energy on static HTML. We recommend using HTML as the preferred offline document.

Export on demand

Recycle bin and log function

The log function is a very important part of team management and safe operation. The tool records every step of the interface operation in detail.

  • Delete a single document
  • Delete a single directory
  • Delete nodes in batch
  • Edit document
  • New document
  • new folder
  • Copy document
  • Generate a copy of the document
  • Change document location
  • Rename
  • Import and Export
  • Permission change

In addition to basic records, the tool also provides a very rich search. In some operations, the user may want to obtain more detailed log information. For example, for editing a document, the user may want to know what has been changed. The tool currently has limited support in this regard, and will continue to improve this content in the future.

Log Function

Recycle Bin Function
## Interface preview

The tool distinguishes two states of interface entry and interface preview . The purpose of interface entry is to achieve efficient entry, and the purpose of interface preview is to achieve efficient retrieval. Unlike other tools that export data, the tool has made some optimizations in terms of retrieval and preview.

In the actual project development, the joint debugging personnel are more concerned about the last few pieces of data modified by someone, and the data can be retrieved very efficiently through the filter conditions.

Support rich filter conditions

Compared with the json display in tabular form, the following presentation format is very friendly to developers.

[Json display with remarks]

Interface preview interface

Mock function

You can use the Mock function for rapid development. Like most interface tools, we support Mock.js syntax. At the same time, we simplify the entire mock process without any additional configuration. The tool will start a mock server locally, and you can simply use this server as a back-end server.

Limited by the browser, only the client can start the Mock server

automated test

Unfortunately, this feature is not currently supported, but we have started to develop this very important feature.

Secondary development & deployment

Client technology stack

  • Vue
  • ElementUI
  • Electron

Server technology stack

  • Egg.js
  • MongoDB

Currently, most of the open source interface tools only provide documentation for use and deployment, and secondary development is more difficult for users. In order to prolong the life of the project and to attract more developers to participate, we have taken the improvement of development documents and product design ideas as one of the most important development tasks. Due to the complexity of the project itself, complete development documentation will take up a lot of open time, and documentation will have a certain lag.

Due to personal technical limitations, the code cannot be very elegant, but the attitude is still correct, and some comments will still be written very seriously!

[Annotation information with correct attitude]

Product design ideas

Development Document

Deployment document

summary

We hope to provide users who are looking for interface management tools with one more choice, and at the same time continue to improve product design and development documents, hoping to attract more people to participate in the project.