(Swagger) a terminal and background development to API interface management tools

Swagger is a normative and complete framework for generating, describing, invoking, and visualizing RESTful Web services. The overall goal is to have the client and the file system update at the same speed as the server. File methods, parameters and models are tightly integrated into the server-side code, allowing the API to always stay in sync. Swagger making deployment management and using powerful APIs has never been easier.

In order to facilitate the management of the Project API interface, in the Internet to find a lot of information on API interface management, feel that the most popular is swagger, powerful, beautiful UI interface, and support online testing and so on

Swagger–the World's most Popular Framework for apis.-(open tool)

Front-end separation

In the current trend, front-to-back separation is almost the industry's consensus on how to develop and deploy. The so-called front-end separation, not in the traditional industry by Sector Division, some people only do the front end (html/css/javascript, etc.), the other part of the people only do the backend (or called the server), because this way is not working: for example, many teams take the back-end template technology (JSP, Freemarker, ERB, etc.), front-end development and debugging requires the support of a background web container that does not allow for true separation of front-end development and deployment.

Usually, the front and back end have their own development process, build tools, testing and so on. No one who does the front end will want to use Maven or Gradle as a building tool, and no one who does the backend will want to use grunt or gulp as a building tool. The front and back ends only work through the interface, which may be a restful interface in JSON format or XML, with the emphasis on the backend being responsible only for the provision and computation of the data and not the presentation at all. The front end is responsible for getting the data, organizing the data and showing the work. This structure is clear and the focus is separated, and the front and rear ends become relatively independent and loosely coupled. But this idea is still very idealistic, and the front-end integration is often a very headache problem. For example, at the end of the need to integrate, we found that the first to negotiate a good data structure has changed, and this change is often unavoidable, which will increase the amount of integration time.

In the final analysis, the front-end or back-end perception of the change period is too long, can not be "timely negotiation, early resolution", resulting in a centralized outbreak. How to solve this problem? We need to negotiate some contracts in advance and use them as intermediate products that can be tested, and then the front and back ends are tested by automated tests, and the tests fail as soon as the contract changes. In this way, each failed test drives the two parties to negotiate again, effectively shortening the feedback period and reducing the integration risk. In the practical way, please join my colleague's blog post, "The front and back end is separated, then?" "Http://icodeit.org/2015/06/whats-next-after-separate-frontend-and-backend/.

However, discipline alone is not enough, and there is a need to improve efficiency through the aid of tools. Let's take a look at how an API design tool,--swagger, will help us achieve a better "front-end separation".

Swagger

Swagger including libraries, editors, code generators and many other parts, here we mainly talk about Swagger editor. This is a fully open source project, and it is also a success story based on angular, we can download the source code and deploy it ourselves, or we can modify it or integrate it into our own software.

In Swagger editor, we can define our RESTful API based on YAML syntax, which then automatically generates a beautifully formatted API document and provides a real-time preview. I believe most of my friends have encountered such a scene: Clearly called the previously agreed API, get the results are not wanted. Perhaps because someone has modified the interface of the API, but forgot to update the document, or the document is not updated in time, or the document is written in ambiguous, everyone's understanding is different. In summary, it is valuable to have the API documentation always updated with the API definition. Let's take a look at the benefits that swagger brings to us in an example.

First we need to install a swagger Editor, or we can use the online version http://editor.swagger.io/directly. If you need to start the editor locally, execute the following three-line command (if node. js is already installed):

Once we have modified the API definition, we can see the API documentation on the right side of the editor and will always be up to date.

Contract Testing

When it comes to the separation of the front and back, it is inevitable that there will be some integration problems: a set of people in a dedicated front-end development, and another one in mind without distractions to do the backend development, then who should pay for the integration? In this era of continuous integration and continuous delivery, how do we ensure that the two sides will not go their separate ways, the farther away?

Therefore, in the beginning of a contract is a matter of urgency, the two sides on the API-related content, including the path, parameters, types and so agree, of course, this contract is not once created can not be modified, and, if initially not designed, it is likely to be frequently modified. At this point, it becomes a challenge for both parties to be able to track the latest APIs in real time. Fortunately, after summing up the experience and lessons of our predecessors, we have already had a strategy to deal with, that is 契约测试 .

As early as 2011, Martin Fowler published a blog http://martinfowler.com/bliki/IntegrationContractTest.html, specifically discussing how to do a contract test.

First, let's assume that we already have a contract that might be JSON-based and possibly XML-based, which doesn't matter. The front end then builds a mock server based on the contract, and all the tests are sent to the mock server. There are two reasons: one is that the API may not have been developed at this time, and the second is that it may be unstable or time-consuming to invoke the real backend API directly due to other reasons such as network. Here, there may be someone to say, if the background API implementation and the previous agreement is not the same, how can we ensure that the integration of the two sides can also be a smooth integration? In fact, this problem is not difficult, just to let the front-end of the test periodically connected to the real API to perform once can be early detection of differences. For example, add a job to our usual build pipeline, and let these tests run through the real API every day in the middle of the night. If, on the next day, some of these tests fail, then you need to communicate with the person who developed the background API, and it is possible that the API is in place when it is implemented, because the actual business logic has changed, and if so, Then the corresponding test and contract definitions need to be updated to meet the latest business requirements.

In conclusion, the purpose of the contract testing is to identify differences as early as possible and make adjustments to minimize the risk of eventual integration.

(Swagger) a terminal and background development to API interface management tools