Use Swagger2 as a document to describe your interface information

Knowledge changes fate, masturbation makes me happy, how is your hair line? This article corresponds to the source code cloud (Gitee) warehouse gitee.com/minbox-proj… Your Star is the biggest motivation for me

Interface document in both before and after the separation is an essential part of the project, the document writing has always been a headache thing, write the program does not write comments, not write a document that is the common fault of the programmer, almost Swagger2 generation brought dawn to the programmers, need only on the interface of a class or interface method to add annotations configuration, In addition to being applied to single applications, it can also be used in microservices architecture, just need to integrate Zuul can achieve document integration of various services.

ApiBoot links required for this article:

• ApiBoot website
• ApiBoot full component series of articles
• ApiBoot Gitee Source Repository (welcome Contributor)
• ApiBoot GitHub source repository (welcome Contributor)

preface

ApiBootSwagger encapsulates Swagger2 internally and requires only an annotation @enableapiBootSwagger for integration, which is very simple to use.

ApiBoot Swagger provides a number of default configurations, such as: If you need to modify the default configuration of document title, document description, document version number, etc., you only need to customize the corresponding configuration parameters in the application.yml file, saying no to the tedious code configuration. ApiBoot realizes this through automatic configuration. You can view ApiBootSwaggerAutoConfiguration configuration class source code for details.

ApiBoot Swagger supports online debugging of integrated OAuth2 interfaces by setting valid AccessToken in the document interface through the “Authorize” button.

Parameters can be configured

ApiBoot Swagger can achieve Swagger2 integration with only one annotation, which is inevitably supported by a lot of configuration parameters. Only by understanding the role of each configuration parameter, can we carry out customized adjustment to our heart’s content.

IO /zh-cn/docs/… Apiboot.minbox. IO /zh-cn/docs/…

Creating a sample project

Let’s start by creating a SpringBoot application and adding ApiBoot dependencies to the project’s POM.xml file, as follows:

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-swagger</artifactId>
  </dependency>

</dependencies>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.minbox.framework</groupId>
      <artifactId>api-boot-dependencies</artifactId>
      <version>2.2.1. RELEASE</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
Copy the code

Enable ApiBoot Swagger

Enable the ApiBootSwagger with the @EnabLeapiBootSwagger annotation, which can be configured on the XxxApplication entry class or on the Configuration class modified by the @Configuration annotation.

@SpringBootApplication
@EnableApiBootSwagger
public class ApibootSwaggerDescribeTheInterfaceApplication {

    public static void main(String[] args) { SpringApplication.run(ApibootSwaggerDescribeTheInterfaceApplication.class, args); }}Copy the code

Modifying Default Configurations

The configuration parameters provided by ApiBoot Swagger can be set or modified in the application.yml file. The following is the configuration with modified version number and title:

ApiBoot configuration
api:
  boot:
    swagger:
      Configure the document title
      title: Interface documentation
      Configure the document version
      version: v1.0
Copy the code

Test controller

To illustrate the power of the Swagger document, let’s create a test controller that uses the annotations provided by Swagger to describe the test interface, as follows:

/** * Example controller **@authorHeng Yu Teenager */
@RestController
@RequestMapping(value = "/user")
@Api(tags = "User controller")
public class UserController {
    /** * Example: * Querying basic user information based on the user name **@param name {@link UserResponse#getName()}
     * @return {@link UserResponse}
     */
    @GetMapping(value = "/{name}")
    @ApiOperation(value = "Query user information", response = UserResponse.class)
    @ApiResponse(code = 200, message = "success", response = UserResponse.class)
    public UserResponse getUser(@PathVariable("name") String name) {
        return new UserResponse(name, 25);
    }
    /** * Response entity example */
    @ApiModel
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class UserResponse {
        @ApiModelProperty(value = "Username")
        private String name;
        @ApiModelProperty(value = "Age")
        privateInteger age; }}Copy the code

Note: ApiBoot Swagger only encapsulates Swagger to achieve fast integration. Internal annotations and configurations are not modified.

Run the test

Start the project source code in this chapter, visit: http://localhost:8080/swagger-ui.html to check the running effect, as shown in the figure below:

When we click on “User Controller” we can expand the list of interfaces defined in that Controller, each of which provides “Try it out” functionality.

OAuth2 is not integrated in this chapter, and AccessToken is not required to perform online debugging.

Type on the blackboard and underline

The implementation of ApiBoot Swagger is mainly attributed to SpringBoot custom Starter, which implements conditional configuration control object instantiation according to configuration parameters and imports configuration classes required by Swagger through @import.

Code sample

If you like this article please click Star for source repository, thanks!! Example source code for this article can be obtained under the directory APIboot-swagger-describe-the-interface:

• Gitee:gitee.com/minbox-proj…

Author’s personal blog uses the open source framework ApiBoot to help you become an Api service architect