How spring MVC uses swagger2 to build dynamic restful APIs

preface

This article mainly introduces the related content of spring MVC using swagger2 to build dynamic restful API. When multiple terminals (Web / mobile terminal) need common business logic, restful style services are generally built for multiple terminals.

In order to reduce the cost of frequent communication with the corresponding terminal development team, we will create a restful API document to record all interface details at the beginning.

However, with the advancement of the project, the problems exposed by doing so are becoming more and more serious.

a. There are many interfaces and complex details (different HTTP request types, HTTP header information and HTTP request content need to be considered). It is very difficult to create this document with high quality.

b. Constantly modifying the interface implementation must synchronously modify the interface document, and the document and code are in two different media. Unless there is a strict management mechanism, it is easy to lead to inconsistency.

Based on this, the project team introduced swagger earlier. After the precipitation of several projects, it has indeed achieved very good results.

Swagger is a normative and complete framework for generating, describing, invoking, and visualizing restful web services.

The methods, parameters and models of the service are closely integrated into the server-side code, so that the maintenance documents and adjustment code are integrated, and the API is always synchronized.

This paper mainly describes the integration process of swagger and spring MVC and some problems encountered. It is only right to throw a brick to attract jade. Specific projects are analyzed in detail.

1. Maven dependency and minimal configuration

Spring context swagger configuration:

< MVC: Resources / > spring MVC handles static resources and adds some useful value-added functions.

a. < MVC: Resources / > allows static resources to be placed anywhere, such as under the WEB-INF directory, class path, etc., completely breaking the restriction that static resources can only be placed under the root path of the web container.

b. < MVC: Resources / > optimize static resources according to the current famous browser optimization principles such as page speed and Yslow.

Swaggerconfig configuration class:

For which request method APIs are generated? Swagger provides the following methods of the requesthandlerselectors object to limit the scope:

2. Service annotation configuration practice

After the above operations, in fact, swagger has been integrated. In the process of project development, you only need to add corresponding annotations on the corresponding restful services.

@API: Annotation on a class to explain the function of the class. You can mark a controller class as a swagger document resource. Usage:

@Apioperation: Annotation on the method, describing the function of the method, the definition of each URL resource, and the use method:

@Apiparam, @ apiimplicitparam: annotate the parameter to explain the function and usage of the parameter:

The above are the simplest configurations. It is enough to build clear API documents. Of course, there are rich annotations. Just know.