Use Spring Boot and Swagger to build RESTful API documentation

In today's web development, RESTful API has become a very popular way for developers to build websites and applications. Using RESTful API, developers can build clear APIs to interact with other applications or services more conveniently. In order to better manage and maintain these APIs, document writing and management have also become a very critical part.

Spring Boot is a framework for quickly building Java applications, which is simple, fast, and easy to expand. Swagger is a tool specifically used to design, build and document RESTful APIs. It can quickly generate RESTful API documents and automatically generate sample flows of API requests and responses.

This article will introduce how to use Spring Boot and Swagger to build RESTful API documents.

1. Create a Spring Boot project

First, we need to use Spring Initializr to create a Spring Boot project, which can be created through https://start.spring.io/. Here, we select the two dependencies Web and Swagger 2. After the creation is completed, we import the project into the integrated development environment and add the Swagger dependency in pom.xml:

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2. Create a RESTful API

Here we create a simple RESTful API for generating a random number.

We add a method in the Controller:

@RestController
public class NumberController {
 
   @ApiOperation(value = "Generate a random number between 1 and 100")
   @RequestMapping(value = "/generateNumber", method = RequestMethod.GET)
   public ResponseEntity<Integer> generateNumber() {
       Random random = new Random();
       int randomNumber = random.nextInt(100) + 1;
       return ResponseEntity.ok(randomNumber);
   }
}

It should be noted that not only the @RestController annotation needs to be added to the class, but also the @Api annotation needs to be used to describe the role of this Controller.

Decompiled content:

package com.example.demo.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
public class NumberController
{

    public NumberController()
    {
    }

    @ApiOperation(value="Generate a random number between 1 and 100")
    @RequestMapping(value="/generateNumber", method=RequestMethod.GET)
    public ResponseEntity generateNumber()
    {
        Random random = new Random();
        int randomNumber = random.nextInt(100) + 1;
        return ResponseEntity.ok(new Integer(randomNumber));
    }
}

3. Configuring Swagger

After completing the development of the corresponding Controller, we need to configure Swagger. Add Swagger related configuration to the Spring Boot configuration file application.properties.

#指定Swagger API扫描的路径
swagger.basePackage=com.example.demo.controller
 
#应用名称
swagger.title=Spring Boot Swagger Example
 
#版本号
swagger.version=1.0.0
 
#描述信息
swagger.description=This is a demo service for Spring Boot Swagger.
 
#联系人信息
swagger.contact.name=John Doe
swagger.contact.url=http://www.example.com
swagger.contact.email=john.doe@example.com

Annotation description:

@Api: Used to describe the role of Controller, similar to the @Controller and @RequestMapping annotations in Spring MVC.

@ApiIgnore: used for ignored APIs and will not be displayed in the generated API documentation.

@ApiOperation: used to describe specific API operations, including method name, request method, request parameters, return object and other information, which can be placed on the method or class.

@ApiImplicitParam: used to describe request parameters, including parameter name, parameter type, necessity and other information.

@ApiModel: used to describe JavaBean classes.

@ApiParam: used to describe parameter information.

@ApiResponses: Used to describe API responses, including HTTP status code, response data and other information.

@ApiProperty: used to describe the property information of the JavaBean class.

4. View API documentation

After completing the above configuration, we start the Spring Boot application and visit http://localhost:8080/swagger-ui.html. We can view the generated API documentation in the browser. Here we can view the detailed information of the API we just wrote, including request method, request parameters, return results, etc. At the same time, Swagger can also generate a sample stream of requests and responses to facilitate developers to reference and test.

Here, we use Spring Boot and Swagger to build RESTful API documentation. Using this method, developers can build and manage their own API documents more quickly, improving development efficiency and maintainability.

The above is the detailed content of Use Spring Boot and Swagger to build RESTful API documentation. For more information, please follow other related articles on the PHP Chinese website!