知識庫 / Spring / Spring Boot RSS 訂閱

以下是片段:

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", 
  date = "2021-03-22T23:26:32.308871+05:30[Asia/Kolkata]")
@Validated
@Api(value = "pets", description = "the pets API")
public interface PetsApi {
    /**
     * GET /pets : List all pets
     *
     * @param limit How many items to return at one time (max 100) (optional)
     * @return A paged array of pets (status code 200)
     *         or unexpected error (status code 200)
     */
    @ApiOperation(value = "List all pets", nickname = "listPets", notes = "", 
      response = Pet.class, responseContainer = "List", tags={ "pets", })
    @ApiResponses(value = { @ApiResponse(code = 200, message = "A paged array of pets", 
      response = Pet.class, responseContainer = "List"),
      @ApiResponse(code = 200, message = "unexpected error", response = Error.class) })
    @GetMapping(value = "/pets", produces = { "application/json" })
    default ResponseEntity<List<Pet>> listPets(@ApiParam(
      value = "How many items to return at one time (max 100)") 
      @Valid @RequestParam(value = "limit", required = false) Integer limit) {
        return getDelegate().listPets(limit);
    }

    // other generated methods
}

其次，由於我們使用了委託模式，OpenAPI 還為我們生成了一個名為 PetsApiDelegate 的委託接口。

特別是，該接口中聲明的方法默認返回 HTTP 狀態碼 501 Not Implemented：

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", 
  date = "2021-03-22T23:26:32.308871+05:30[Asia/Kolkata]")
public interface PetsApiDelegate {
    /**
     * GET /pets : List all pets
     *
     * @param limit How many items to return at one time (max 100) (optional)
     * @return A paged array of pets (status code 200)
     *         or unexpected error (status code 200)
     * @see PetsApi#listPets
     */
    default ResponseEntity<List<Pet>> listPets(Integer limit) {
        getRequest().ifPresent(request -> {
            for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
                    String exampleString = "{ \"name\" : \"name\", \"id\" : 0, \"tag\" : \"tag\" }";
                    ApiUtil.setExampleResponse(request, "application/json", exampleString);
                    break;
                }
            }
        });
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
    }

    // other generated method declarations
}

之後，我們看到 有一個 PetsApiController 類，它只是將委託器連接起來：

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", 
  date = "2021-03-22T23:26:32.308871+05:30[Asia/Kolkata]")
@Controller
@RequestMapping("${openapi.swaggerPetstore.base-path:}")
public class PetsApiController implements PetsApi {

    private final PetsApiDelegate delegate;

    public PetsApiController(
      @org.springframework.beans.factory.annotation.Autowired(required = false) PetsApiDelegate delegate) {
        this.delegate = Optional.ofNullable(delegate).orElse(new PetsApiDelegate() {});
    }

    @Override
    public PetsApiDelegate getDelegate() {
        return delegate;
    }
}

在 modelPackage 中，生成了若干個數據模型 POJO，名為 Error 和 Pet，這些 POJO 基於我們 YAML 輸入中定義的 schemas 而生成。

讓我們來看其中之一——Pet：

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", 
  date = "2021-03-22T23:26:32.308871+05:30[Asia/Kolkata]")
public class Pet {
  @JsonProperty("id")
  private Long id;

  @JsonProperty("name")
  private String name;

  @JsonProperty("tag")
  private String tag;

  // constructor

  @ApiModelProperty(required = true, value = "")
  @NotNull
  public Long getId() {
    return id;
  }

  // other getters and setters

  // equals, hashcode, and toString methods
}

5. 測試服務器

現在，為了使服務器樁作為一個服務器正常運行，只需要實現 delegator 接口的實現。

為了保持簡單，我們不會在這裏進行操作，而是隻測試樁。

此外，在進行測試之前，我們需要一個 Spring Application：

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

5.1. 使用 curl 測試

啓動應用程序後，我們只需運行以下命令：

curl -I http://localhost:8080/pets/

以下是預期結果：

HTTP/1.1 501 
Content-Length: 0
Date: Fri, 26 Mar 2021 17:29:25 GMT
Connection: close

5.2. 集成測試

或者，我們可以為相同功能編寫一個簡單的集成測試：

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
public class OpenApiPetsIntegrationTest {
    private static final String PETS_PATH = "/pets/";

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void whenReadAll_thenStatusIsNotImplemented() throws Exception {
        this.mockMvc.perform(get(PETS_PATH)).andExpect(status().isNotImplemented());
    }

    @Test
    public void whenReadOne_thenStatusIsNotImplemented() throws Exception {
        this.mockMvc.perform(get(PETS_PATH + 1)).andExpect(status().isNotImplemented());
    }
}

6. Spring Boot 3.0 版本及 jakarta 命名空間

此外，我們的配置在 Spring Boot 版本 3.0 之前的項目上都能正常工作。但是，從 Spring Boot 3.0 開始，javax 命名空間已被jakarta 命名空間所取代。

因此，為了生成與 Spring Boot 3.0 及更高版本兼容的代碼，我們需要修改插件配置中的 configOptions 選項：

<configOptions>
     // ... 
    <useSpringBoot3>true</useSpringBoot3>
</configOptions>

在這裏，我們添加了 useSpringBoot3 選項並將其設置為 true。此選項默認啓用 jakarta 命名空間。

或者，我們可以指定 useJakartaEe 選項，在 configOptions 中。

<configOptions>
     // ...
    <useJakartaEe>true</useJakartaEe>
</configOptions>

通過將 useJakartaEe 選項設置為 true，生成的代碼將使用 jakarta 命名空間，並且不會出現編譯錯誤。

值得注意的是，在 Spring Boot 3.0 項目中同時定義這兩個選項是多餘的，因為 useSpringBoot3 選項默認會啓用 useJakartaEe 選項。

7. 結論

在本文中，我們瞭解到如何使用 OpenAPI 生成器 Maven 插件，從 YAML 規範生成基於 Spring 的服務器樁。

作為下一步，我們還可以使用它來生成客户端。