【Spring Boot 升级系列】微服务接口开发

前言

到目前为止，我们已经了解了如何生成一个新的 spring boot 应用程序，然后如何将其容器化。但是，我们的应用程序没有任何功能。今天我们将学习如何使用 Spring boot 创建 REST API。我们将采用模式优先的方法生成 REST API 接口，本文将采用 OpenAPI 规范以及如何使用该规范生成 REST API 接口。

一、OpenAPI 规范

API 是应用程序与应用程序使用者之间的契约。这些消费者可以是机器，也可以是人类。OpenAPI 是一种以人类和机器可读格式编写 API 合约的规范，它标准化了我们描述 API 的方式，整个说明可以在这里找到 https://spec.openapis.org/oas/v3.1.0 。

二、OpenAPI 规范引入

我们创建一个新服务，称之为 inventory-service。我们现在知道如何生成新的 Spring Boot 应用程序。我们在 src/resources/spec/inventory-api.yml 中添加了一个 yml openAPI 规范文件。配置文件如下所示：

openapi: "3.0.3"
info:
  title: inventory-api
  version: 1.0.0
paths:
  /products:
    get:
      description: Get All Products
      operationId: getAllProducts
      responses:
        '200':
          description: All products are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfProducts'
        '404':
          description: No Product returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      description: Add A Product to inventory
      operationId: addProduct
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Product added successfully
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{
   
   id}:
    get:
      description: Get A Product By ID
      operationId: getProductById
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Get a product by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: No Product returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      description: Update A Product
      operationId: updateProduct
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Created product is  returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product Does not Exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListOfProducts:
      type: array
      items:
        $ref: '#/components/schemas/Product'

    Product:
      type: object
      properties:
        id:
          type: string
          format: UUID
    Error:
      type: object
      properties:
        message:
          type: string

这是一个非常小的API ，我们可以在路径部分看到我们对 API 的描述，每个 API 端点都有其可选的请求正文和响应正文，我们还可以定义是否需要一些自定义标头、路径参数、查询参数等。

在组件部分，我们定义了模型，这些模型在我们的 API 中被引用。我不会更深入地研究 OpenAPI 规范，但因为它非常庞大，但我们始终可以针对我们的特定用例查阅该规范。

三、生成 REST API

现在我们有了 OpenAPI 规范，有一些插件和工具可用于从我们的规范中生成代码。我们可以使用 openapi-generator https://openapi-generator.tech/docs/installation 来生成我们的 REST API，也可以使用 cli 来生成我们的 REST API。还有一个 maven 插件 https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin 我们将使用它来生成我们的源代码。

maven 插件使用 openapi-generator 生成源代码，要使用 maven-plugin，我们会将其添加到构建部分，如下所示 -

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.4.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/spec/inventory-api.yml</inputSpec>
                <generatorName>spring</generatorName>
                <generateSupportingFiles>false</generateSupportingFiles>
                <configOptions>
                    <basePackage>com.sab.inventory</basePackage>
                    <sourceFolder>src/java/main</sourceFolder>