[Roast：Day - 無需 AI 自動建立 API 伺服器

為了將我的前端介面連接到資料庫，我需要設計一個 API 來允許前端應用程式檢索和發送資料。這將啟用我的用戶邏輯，例如建立帳戶、登入和登出等。它將啟用圍繞烘焙的所有邏輯。

我之前曾建立過 Express API，但這次我想看看是否可以在建置過程中了解更多有關 Swagger 的知識。

招搖套房

Swagger 是一家設計和維護三種產品的公司，Swagger Editor、Swagger CodeGen 和 Swagger UI。這三個產品攜手合作，讓創建符合 OpenAPI 的應用程式（和文件）變得更加容易！

使用合約

使用 Swagger 建立 API 的過程從 Swagger 編輯器開始。該工具允許您創建所謂的合約。合約是一個 YAML 文檔，它定義了有關應用程式的不同內容，例如名稱、它將處理的路由等等。

YAML 與 JSON

如果您以前沒有使用過 YAML，它是一種更寬鬆的基於物件的標記語言，與 JSON 有一些相似之處，但更容易快速輸入。以下是 JSON 和 YAML 中相同內容的範例：

// JSON Example
{
  "name": "ThisApp",
  "description": "An example of data.",
  "list": [
    "option1",
    "option2",
    "option3"
  ],
  "object": {
    "key": "value"
  }
}

# YAML Example
name: ThisApp
description: An example of data.
list:
  - option1
  - option2
  - option3
object:
  key: value

請注意，YAML 雖然仍然是機器可讀的，但對於人類來說也更容易閱讀，這使其成為此規範的絕佳標記語言。

定義 API 規範

使用 Swagger 編輯器並遵循 OAS，您可以編寫通常編程到 API 中的所有內容。

在頂層，您將定義應用程式的細節：

openapi: 3.0.3
info:
  title: Roast - Know Your Home Roasts
  description: # This will appear in the API UI
  version: 1.0.0
servers:
  - url: # A url to one or more servers here
tags:  These are groups of paths
  - name: user
    description: Operations for your user
  - name: roast
    description: Access to roasts
paths:
  # Define all of your paths in this object
components:
  # Define reusable pieces of code here

當您開始定義路徑時，程式碼編輯器的魔力就會顯現出來。採用我定義的以下路徑，透過 id 取得單一烘焙。

# ... contract information
paths:
  # ... users paths, etc.
  /roasts/{roastId}:
    get:
      tags:
        - roast
      summary: Get roast by id
      description: Must include a valid roast id
      parameters:
        - $ref: '#/components/parameters/roastIdParam'
      responses:
        '200': 
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Roast"
        '400':
          $ref: '#/components/responses/Invalid'
        '404':
          $ref: '#/components/responses/NotFound'

讓我們分解這個物件。首先，它被稱為/roasts/{roastId}。這意味著我們正在定義當請求發送到此路由時伺服器的預期行為。下面會發生什麼事？

• get：這告訴 Swagger 工具我們要為此路徑定義 GET 請求端點，有關 GET 請求的其餘資訊將位於該物件內。
• 標籤：這是端點的一項可選屬性，但在 UI 中非常有用，因為它允許您在文件中對端點進行分組。
• 摘要：和描述：在 Swagger UI 的螢幕渲染中，您將在不同的位置看到這兩個欄位。摘要提供了端點功能的快速說明，描述提供了額外的詳細資訊。
• 參數： get: 的這個屬性是可以指定路徑參數的地方。您可以包含諸如是否需要參數以及期望的資料類型之類的資訊。
• 回覆： 這是肉和馬鈴薯。標識為狀態代碼字串，來自端點的每個有效回應都可以在此處列出，以用於文件和程式碼產生目的。

保持組件乾燥

開發這樣的合約，您可能會發現自己一遍又一遍地輸入相同的內容。作為一名程式設計師，您可能知道我們要遵循 DRY 原則：「不要重複自己」。例如，當定義一個必要的請求體時，可能會有多個端點需要同一個物件。

這就是組件的用武之地。對於這個範例，您可以定義一個架構，然後使用 $ref 在合約中的任何位置引用該架構： .

所以，在我的合約底部，我有一個組件：物件。

components:
  schemas:
    Roast: # An arbitrary name to identify the schema
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        ## Include all other properties

這個組件物件包含一個名為 Roast 的模式，所以現在，如果我需要指定需要在請求中發送該對象，例如在對 /roast 的 POST 請求中發送以添加新的烘焙。我可以這樣引用該物件：

/roast:
  post:
    # additional specifications
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Roast'

您也可以在定義參數和規範的許多其他重複部分中執行此操作！

自動記錄

當您在 Swagger 編輯器中打字時，右側視窗中的 Swagger UI 一直在不斷更新。 Swagger UI 正在更新將成為您的 API 文件的內容！這意味著您不必稍後返回並自己編寫文件。

最好的部分是，它將與您的應用程式一起提供（只要您使用 CodeGen 建立它）。

Let Swagger Code Your API Too!

Once you feel like your API is up to spec, you can have a working server in 17 different languages/frameworks in seconds! Just click Generate Server, and select your flavor and CodeGen reads your OAS spec and downloads a server.

In Node, your code comes out in a few different directories.

generated-server/
|-- api/
|-- controllers/
|-- service/
|-- utils/
|-- README.md
|-- index.js
|-- package.json

The api directory contains your OpenAPI spec. The controllers directory contains a file for each of your path groups, with exported functions specifically for handling the unique paths and operations of your application. The service directory, is where you will hook these operations up to your database and perform the business logic of the application, and utils contains functions that help read and write data.

Your server will actually live in index.js.

Is It Really That Easy?

Yes! Well, sort of.

CodeGen does in fact make a working server for you, but it's still up to you to hook up the database and design the logic of the application! But, it gives you a complete and organized skeleton that you can work in!

Here's an example of the code that it output for my POST request to /roasts .

// controllers/Roast.js
// ...
module.exports.addRoast = function addRoast (req, res, next, body) {
  Roast.addRoast(body)
    .then(function (response) {
      utils.writeJson(res, response);
    })
    .catch(function (response) {
      utils.writeJson(res, response);
    });
};

// service/RoastService.js
// ...
exports.addRoast = function(body) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
  "notes" : "Doesn't taste as good as last time... I wonder if the weather is making the beans roast faster now that it's warmer",
  "heatLevel" : "Med",
  "origin" : "Ethiopian",
  // ...
  "id" : 10,
};
    if (Object.keys(examples).length > 0) {
      resolve(examples[Object.keys(examples)[0]]);
    } else {
      resolve();
    }
  });
}

The above code was entirely generated by Swagger CodeGen. However, it won't actually add a roast object anywhere. This is creating a mock object and sending it back. But, after hooking up a Postgres database, and creating queries with this logic inside the service, the API will be fully operational!

Would You Use It?

I loved working with Swagger on this API, it was the first time that I committed to learning some of the intricacies of OAS to generate the server. The only rub that I have with it is that the docs are not formatted the best, and they can be hard to navigate searching for what you want to add to the server.

But, once you're familiar with OAS, this tool can save a ton of time. Not only do you have extremely thorough documentation when you're done, but you can treat the generated code as a to-do list of the functions and logic that you need to implement as you build!

Would you give it a try?

---

Check Out the Project

If you want to keep up with the changes, fork and run locally, or even suggest code changes, here’s a link to the GitHub repo!

https://github.com/nmiller15/roast

The frontend application is currently deployed on Netlify! If you want to mess around with some features and see it in action, view it on a mobile device below.

https://knowyourhomeroast.netlify.app

Note: This deployment has no backend api, so accounts and roasts are not actually saved anywhere between sessions.

以上是[Roast：Day - 無需 AI 自動建立 API 伺服器的詳細內容。更多資訊請關注PHP中文網其他相關文章！