Shulou(Shulou.com)06/03 Report--

What is the configuration of integrating Swagger in Swagger and SpringBoot? I believe many inexperienced people don't know what to do about it. Therefore, this article summarizes the causes and solutions of the problem. Through this article, I hope you can solve this problem.

Swagger introduction 1. What is Swagger?

As a back-end program development, we have more or less written several background interface projects, whether it is to write the mobile phone interface, or the hot front-end and back-end separation projects, the front-end and back-end are developed by different engineers, so the communication between them is connected through interface documents. However, it is often accompanied by many problems, the back-end programmers think that it takes too much time and energy to write interface documents and maintenance, and the front-end programmers think that interface documents are not updated in time, which leads to the travel problem of calling each other between programs. So can it simplify the writing of interface documents and generate them automatically? Of course! In this way, Swagger, a tool for automatic online generation of interface documents, was born.

Swagger is a specification and complete framework for generating, describing, invoking, and visualizing RESTful-style Web services. The overall goal is to have the client and the file system update at the same speed as the server. The file's methods, parameters, and models are tightly integrated into the server-side code, allowing API to always keep synchronized. Swagger makes it easier for deployments to manage and use powerful API.

Advantages of 2.Swagger

The code changes, the document changes. With a small amount of annotations, Swagger can automatically generate API documents according to the code, which ensures the timeliness of the documents.

Cross-language, supporting more than 40 languages.

Swagger UI presents an interactive API document, and we can try to call API directly on the document page, eliminating the process of preparing complex call parameters.

You can also import document specifications into related tools (such as Postman, SoapUI) that will automatically create automated tests for us.

Integrate Swagger1 into SpringBoot. Basic environment construction

First build a basic SpringBoot project and import the following Swagger initiator

Io.springfoxspringfox-boot-starter3.0.0

Write a controller for testing

/ / java Source Code complete www.1b23.com@RestControllerpublic class HelloController {@ PostMapping (value = "/ hello") public String hello () {return "hello";}}

Write the configuration class for Swagger

@ Configuration@EnableOpenApipublic class SwaggerConfig {}

Run startup input address: http://localhost:8080/swagger-ui/index.html

You can see the Swagger interface documentation page, indicating that the basic configuration environment is successful!

Note:

The address of the Swagger3.0 version is http://localhost:8088/swagger-ui.html of the address accessed in the http://localhost:8088/swagger-ui/index.html Magi 2.x version

two。 Configure Swagger

To configure Swagger, you first need to build its Bean instance Docket object and create a Docket in the SwaggerConfig configuration class you just created

/ / java source code www.1b23.com@Beanpublic Docket docket () {return new Docket (DocumentationType.OAS_30) .apiInfo (apiInfo ());}

Docket (DocumentationType.OAS_30), the parameter we choose here is DocumentationType.OAS_30, which is the interface document version of a Swagger instance, so we choose to use OAS_30. The other types are as follows, corresponding to the historical version of Swagger.

Public static final DocumentationType SWAGGER_12 = new DocumentationType ("swagger", "1.2"); public static final DocumentationType SWAGGER_2 = new DocumentationType (" swagger "," 2.0"); public static final DocumentationType OAS_30 = new DocumentationType ("openApi", "3.0")

To build Docket, you need to create an ApiInfo instance.

/ / java source code Daquan www.1b23.comprivate ApiInfo apiInfo () {/ / author information Contact contact = new Contact ("TIOXY", "https://www.cnblogs.com/tioxy/"," 1369773052@qq.com ") Return new ApiInfo ("Tioxy Interface document", "Project description", "1. 0", "https://www.cnblogs.com/tioxy/", contact,"Apache 2. 0", "http://www.apache.org/licenses/LICENSE-2.0",new ArrayList ());}

The main function of ApiInfo is to build the basic information displayed on the page of our interface document, showing the following location

3. Configure scan interface and switch

The scan interface is configured by the select () method when building the Docket. The complete code of Docket is as follows:

/ / java Source complete www.1b23.com@Beanpublic Docket docket (Environment environment) {/ / set the displayed Swagger environment Profiles dev = Profiles.of ("dev"); / / get the project environment boolean flag = environment.acceptsProfiles (dev) Return new Docket (DocumentationType.OAS_30) .apiInfo (apiInfo ()) / / configure Api document grouping. GroupName ("TIOXY") / / enable () whether Swagger is enabled, default is true.enable (flag) .select () / / RequestHandlerSelectors, configure the way to scan the interface / / basePackage specifies the package / / any () to scan all All interfaces in the project will be scanned to / / none () do not scan / / withClassAnnotation () scan the comments on the class / / withMethodAnnotation () scan method. APIs (RequestHandlerSelectors.basePackage ("com.tioxy.controller")) / / paths () filter a path .build (PathSelectors.any ()) }

GroupName ("TIOXY"): indicates the name of this Docket instance, that is, the instance name selected in the upper right corner of the interface document page. In actual development, we are developed by multiple people, corresponding to multiple Docket instances.

Enable (flag): whether enable () enables Swagger. Default is true.

What we use here is to dynamically configure whether Swagger is enabled, and to obtain the name of the project environment running at this time through Environment. If it is dev, define a flag to dynamically set whether it is enabled or not.

4. Entity class configuration

Create a new User entity class

@ ApiModel ("user entity") public class User {@ ApiModelProperty ("user name") public String username; @ ApiModelProperty ("password") public String password;}

As long as this entity is on the return value of the request interface (even if it is generic), it can be mapped to the entity item:

@ RequestMapping ("/ getUser") public User getUser () {return new User ();}

5. Common notes

We can also add comments to the interface to facilitate us to explain the information of the interface in the interface document, such as the function of the interface, the description of parameters, etc., which is convenient for callers to use.

The Swagger annotation simply states that @ Api (tags = "xxx module description") acts on the module class @ ApiOperation ("xxx interface description") acts on interface methods @ ApiModel ("xxxPOJO description") acts on model classes: for example, VO, BO@ApiModelProperty (value = "xxx property description", hidden = true) acts on class methods and properties, and hidden is set to true to hide the attribute @ ApiParam ("xxx parameter description") acting on parameters, methods and fields. Similar to @ ApiModelProperty after reading the above, do you know how to integrate the configuration of Swagger in Swagger and SpringBoot? If you want to learn more skills or want to know more about it, you are welcome to follow the industry information channel, thank you for reading!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.