使用OpenAPI Generator實現Open API Server

1.概述

顧名思義， OpenAPI Generator會根據OpenAPI規範生成代碼。它可以為客戶端庫，服務器存根，文檔和配置創建代碼。

它支持各種語言和框架。值得注意的是，它支持C ++，C＃，Java，PHP，Python，Ruby，Scala –幾乎所有廣泛使用的工具。

在本教程中，我們將學習如何通過OpenAPI Generator的maven插件實現基於Spring的服務器存根。使用生成器的其他方式是通過其CLI或在線工具。

2. YAML文件

首先，我們需要一個指定API的YAML文件。我們將其作為生成器的輸入，以生成服務器存根。

這是我們的petstore.yml的片段：

openapi: "3.0.0" paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query ... responses: ... post: summary: Create a pet operationId: createPets ... /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById ... components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string

3. Maven依賴

3.1 OpenAPI Generator的插件

接下來，讓我們為生成器插件添加Maven依賴項：

<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>5.1.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec> ${project.basedir}/src/main/resources/petstore.yml </inputSpec> <generatorName>spring</generatorName> <apiPackage>com.baeldung.openapi.api</apiPackage> <modelPackage>com.baeldung.openapi.model</modelPackage> <supportingFilesToGenerate> ApiUtil.java </supportingFilesToGenerate> <configOptions> <delegatePattern>true</delegatePattern> </configOptions> </configuration> </execution> </executions> </plugin>

如我們所見，我們傳入YAML文件作為inputSpec 。之後，由於需要基於Spring的服務器，因此將generatorName用作spring 。

然後apiPackage指定將在其中生成API的程序包名稱。接下來，我們在生成器放置數據模型的地方放置了modelPackage將delegatePattern設置為true ，我們要求創建一個可以實現為自定義@Service類的接口。

重要的**是，無論您使用的是CLI，Maven / Gradle插件還是在線生成選項，OpenAPI Generator的選項**都相同。

3.2 Spring依賴

在生成Spring服務器時，我們還需要其依賴項（ Spring Boot Starter Web和Spring Data JPA ），以便生成的代碼可以按預期進行編譯和運行：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>org.springframework.data</groupId> <artifactId>spring-data-jpa</artifactId> <version>2.4.6</version> </dependency> </dependencies>

4.代碼生成

要生成服務器存根，我們只需要運行：

mvn clean install

結果，我們得到：

現在讓我們看一下代碼，從apiPackage的內容開始。

首先，**我們獲得一個名為PetsApi**的API接口，其中包含YAML規範中定義的所有請求映射。這是代碼段：

@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> 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未實現：

@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 ，基於YAML輸入中定義schemas ，生成Error和Pet的數據模型POJO。

讓我們看看其中一個– 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.測試服務器

現在，要使服務器存根作為服務器發揮作用，所需要做的就是添加委託者接口的實現。

為了簡單起見，在這裡我們不會這樣做，而僅測試存根。此外，在此之前，我們需要一個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()); } }

六，結論

在本教程中，我們看到瞭如何使用OpenAPI生成器的maven插件根據YAML規範生成基於Spring的服務器存根。