preface

At present, there are many API management platforms on the market, and with many of these platforms, development teams need to spend more time to analyze and compare the selection. How to choose an API management tool suitable for their team is very important, because it largely determines the way of collaboration between teams.

Why API management

Traditional API management adopts Word document, which is difficult to maintain and manage and easy to cause synchronization. As time goes by, API documents are scattered all over the place, resulting in inconsistent interface data format and frequent interface errors, which will cause distrust between teams. As a result, API documentation became obsolete; When this happens, developers frequently ask, communicate, co-check, and look at the code to determine the details of the API, making it easier for teams to pass the buck to each other and increasing development costs.

Interestingly, this is not a problem that can be solved by throwing a powerful API management platform at the development team. This requires the use of appropriate management strategies.

What do we really need

From a result-oriented perspective, if we are on the consumer side of the API interface, the API documentation we need must have the following important characteristics:

  1. Describe the appropriate
  2. Division is reasonable
  3. Synchronization in time
  4. Pass the test
  5. Easy to use

At this time, we will find that these things are basically done by people, platforms and tools just provide a better interface, more convenient tools to help us achieve point 3 and 4 faster. That’s when it dawned on us that API management is about people, not tools.

How to manage

Who produces, who manages. To make the idea more palatable, it needs to become a habit, so it’s best to combine it with what the other person does best, put constraints on it, and empower the person.

  • Tools are best used in conjunction with code.
  • Pass the test (constraints).
  • Has the right to define some interfaces.

Platform analysis

Online product

There are a lot of these products, which can be classified as either free or paid, with some offering additional services such as monitoring and automated testing.

advantage

  1. No server needs to be maintained
  2. Provides teamwork capabilities
  3. Provides online interface testing
  4. Interface change notification (not necessarily)
  5. Multi-project management

disadvantage

  1. The platform may cease maintenance at any time
  2. Interfaces need to be manually synchronized
  3. The interface formats of the major platforms are not uniform, and migration is a problem
  4. The interface contract is not guaranteed (does it pass the test? Is the format correct?)

Framework for the integration

Framework integration refers to the integration of API document automatic generation framework into the development environment. Currently, there are mainly Springfox-Swagger2 and Spring Rest Doc based on Spring.

Springfox-Swagger2

disadvantage

  1. invasive
  2. Add a small amount of learning costs

advantage

  1. Security, can define interface access authentication
  2. Code is documentation
  3. The UI is beautiful
  4. Provide test
  5. The community provides spring-Boot integration
Spring REST Doc

The positioning of the product is to test driven API documents, provide a combination of handwritten documents and automatic generation, based on API tests to automatically generate documents, only after the test is passed to generate API documents, so the accuracy of the document can be guaranteed.

disadvantage

  1. Add a small amount of learning costs
  2. Documentation requires a little manual configuration, but configuration is relatively simple
  3. It takes some time to perform API testing before you release the interface

advantage

  1. Secure, selectable document sharing scope
  2. No invasive
  3. Interface contract (can’t generate offline HTML API document until API test passes)
  4. Code is documentation
  5. Spring ecology, easy integration

self-built

When the framework integration and the public network online platform cannot meet the requirements, you can build an API management platform. There are many open source tools for this, and the most common ones are listed in mind maps.

advantage

  1. controllable
  2. Can be customized

disadvantage

  1. Need to maintain the server
  2. Interfaces need to be manually synchronized
  3. The interface contract is not guaranteed (does it pass the test? Is the format correct?)

conclusion

The article expressed my own views on API management, briefly analyzed some API tools on the market, and summarized the advantages and disadvantages of different product choices in a coarse-grained way. The goal of API management is to facilitate team collaboration. Based on the above understanding, I actually find that Spring REST Doc is the best fit.