How to use Swagger to generate API documentation?

With the rapid development of web applications, API documentation is becoming more and more important. API documentation is designed to help developers understand API usage methods and parameters, reducing waste of time and resources. However, manually writing API documentation can be cumbersome and time-consuming. At this time, Swagger becomes a powerful tool for developers. Swagger is a popular API documentation tool that can automatically generate readable and interactive API documentation. In this article, we introduced how to use Swagger to automatically generate API documentation.

What is Swagger?

Swagger is a set of open source tools that help developers build, design, describe and consume RESTful web services. Swagger allows you to write API documentation using YAML or JSON formats for describing API operations and generate interface documentation that is easy to read and interact with.

Swagger supports multiple programming languages ​​and frameworks such as Java, C#, Python and Ruby. It can also integrate with many existing API frameworks, including Spring, Express, Django, etc.

Using Swagger to generate API documents requires installing Swagger UI first. Swagger UI is an interactive API documentation website that is independent of the API and follows the Swagger specification. It provides a beautiful interface for visualizing API documentation and supports automated attempts at API calls.

Step 1: Configure Swagger

To use Swagger, you need to download the Swagger package first, which can be obtained from the Swagger website or downloaded using the dependency manager.

To configure the Swagger API in the Java Spring Boot project, you need to add the following Swagger dependencies in the maven dependencies:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

Among them ${springfox-swagger2.version} and ${springfox-swagger-ui .version} represents the Swagger version number. Enable swagger in the configuration file application.properties:

#开启swagger
swagger.enabled = true

Step 2: Write Swagger annotations

Swagger uses annotations to describe operations and parameters in the API. Add Swagger annotations at the top of the API controller class and its methods so that Swagger can correctly parse and generate documents and display them on the Swagger UI.

The following are some sample annotations:

1. @Api: used to add description information of the API

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

2. @ApiOperation: used to add Description information of API operation

@ApiOperation(value = "获取用户列表", notes = "")
@GetMapping(value = "/list")
public Result getUserList() {
    List<User> userList = userService.listUser();
    return Result.success(userList);
}

3. @ApiParam: Description information used to add API operation parameters

@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户详细信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

Step 3: Start the application and access Swagger UI

After completing writing the Swagger annotations, use a browser to open the address of the Swagger UI. It automatically builds visual API documentation based on your API.

The default address of Swagger UI is: http://localhost:8080/swagger-ui.html

On the Swagger UI interface, you can see an overview of the API and various APIs Description of the interface, request and response parameters, and some test code, etc. This can help developers better understand and use the API.

Summary

Swagger is a powerful API documentation tool that can automatically generate API documentation that is easy to read and interact with. Using Swagger can improve the efficiency and quality of API development and reduce the time and resources required to manually write API documentation. By following the above steps, you can easily start using Swagger to automatically generate API documentation.

The above is the detailed content of How to use Swagger to generate API documentation?. For more information, please follow other related articles on the PHP Chinese website!