本文将向你展示如何使用Swagger UI记录并与你的Spring Boot REST服务互动。为了这个例子的目的，我们将使用springdoc-openapi库。

###开始使用SpringDoc OpenAPI

这个java库可以让你为你的Spring Boot项目自动生成REST API文档。Springdoc-openapi在幕后，在运行时检查应用程序，根据Spring配置、类结构和各种注释推断API语义。

让我们创建一个简单的REST项目作为例子。

spring init -dweb swagger-demo

然后，将SpringDoc OpenAPI的依赖关系添加到其中。

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.6</version>
</dependency>

在我们的项目中，我们将添加一个简约的控制器。

@RestController
public class CustomerController
{
   @Autowired
   CustomerRepository repository;

    @RequestMapping("/list")
    public List<Customer> findAll()
    {
        return repository.getData();
    }

    @RequestMapping("/one/{id}")
    public Customer findOne(@PathVariable int id)
    {
        return repository.getData().get(id);

    }
}

为了简洁起见，我们不包括CustomerRepository和Customer Class。你会发现这个项目的完整源代码在本教程的最后。

也包括一个应用类来引导你的Spring Boot应用。

@SpringBootApplication

public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }

   
}

现在你已经准备好了! 启动你的应用程序。

mvn install spring-boot:run

首先，让我们通过查询控制器的API文档来检查一切是否符合预期。这可以通过以下默认的URL获得。http://localhost:8080/v3/api-docs/ 

接下来，访问Swagger用户界面。http://localhost:8080/swagger-ui/index.html

在这里你可以访问所有可用的REST端点，并使用默认模板来使用HTTP操作。

Swagger UI的默认路径

默认情况下，Swagger UI在以下端点可用。
http://server:port/context-path/swagger-ui.html
要在不同的路径上发布Swagger UI，在你的application.properties文件中设置以下属性。

# swagger-ui custom path
springdoc.swagger-ui.path=/custom-swagger-ui.html

如何定制操作描述

有一组注解，你可以放在你的REST操作上，以提供单一操作的描述。你也可以根据响应代码添加一个自定义的响应描述。

作为一个例子，看一下下面的例子。

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;


@RestController
public class CustomerController
{
   @Autowired
   CustomerRepository repository;

   @Operation(summary = "List all customers")
   @ApiResponses(value = { 
     @ApiResponse(responseCode = "200", description = "Found the following customers", 
       content = { @Content(mediaType = "application/json", 
         schema = @Schema(implementation = Customer.class)) }),
     @ApiResponse(responseCode = "500", description = "Internal server error", 
       content = @Content)}) 
    @RequestMapping("/list")
    public List<Customer> findAll()
    {
        return repository.getData();
    }

    @RequestMapping("/one/{id}")
    public Customer findOne(@PathVariable int id)
    {
        return repository.getData().get(id);

    }
}

正如你所看到的，findAll方法现在有一个自定义的**@Operation**摘要和两个自定义的响应作为响应代码的结果。

你可以应用更多的自定义功能

开箱即用，所有的包都将在Swagger用户界面中可用。为了限制你想从用户界面上访问的包的列表，你可以使用以下属性。

springdoc.packagesToScan=com.sample, com.demo

此外，你可以使用下面的属性来设置要包括的路径列表。

springdoc.pathsToMatch=/v1, /api/balance/**

S源代码

本文的源代码在这里可以找到：https://github.com/fmarchioni/masterspringboot/tree/master/rest/swagger-demd1c1d

通过www.DeepL.com/Translator（免费版）翻译