Web API 實作多語言開發實戰 Swagger 規格與 Express.js、FastAPI 實作

什麼是 Web API 實作？

Web API 實作 是指後端開發者根據預先定義好的規格（如 OpenAPI/Swagger），使用程式語言（如 JavaScript, Python, Java）編寫伺服器端邏輯的過程。其核心目標是建立穩定、高效且符合 RESTful 或 GraphQL 標準的介面，供前端、行動端或第三方系統進行資料交換。實作過程通常包含路由設定（Routing）、參數驗證、資料庫操作以及錯誤處理，並透過自動化文件工具確保前後端協作的一致性。

小編在另外兩篇文章分別介紹了 什麼是 RESTful API 和 API 系統設計方法，談了許多 API 概念上的東西。

這篇文章會從實作的角度，用 JavaScript (Express.js)、Python (FastAPI)、Java (Spring Boot) 來實作後端的 Web API。

實作就是最好的學習，這就跟讀了很多把妹相關的書籍，還不如註冊個交友軟體天天練習跟女生聊天一樣，小編在年初也是因為受到直屬學弟們的鼓勵就真的註冊了而且還天天晚上都在熬夜聊天。

Web API 實作 上主要是兩個步驟：

1. API 規格文件撰寫
2. API 系統實作

API 規格文件撰寫：使用 Swagger/OpenAPI 定義介面

在進行 Web API 實作 之前，撰寫詳細的 API 規格文件 是確保前後端協作順暢的關鍵步驟。這裡我們手動進行 Swagger (現稱為 OpenAPI) 的 YAML 撰寫，撰寫語法並不困難，核心圍繞 API 的輸入及輸出兩大重點。

1
2
3
4
5
6
7

definitions:
  Book:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"

1. 輸入: 定義路徑與 HTTP 方法及輸入參數

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

paths:
  /api/v1/book/{bookId}:
    get:
      tags:
        - "Book"
      summary: "Find Book by ID"
      description: "For valid response try integer IDs with value >= 1"
      operationId: "getBookById"
      produces:
        - "application/json"
      parameters:
        - name: "bookId"
          in: "path"
          description: "ID of pet that needs to be fetched"
          required: true
          type: "integer"
          maximum: 10.0
          minimum: 1.0
          format: "int64"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Book"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Order not found"

各位大大可以自行複製完整的版本到線上的 Swagger Editor 看看結果。
Swagger Editor: https://editor.swagger.io/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

swagger: "2.0"
info:
  description: "API 文件"
  version: "1.0.0"
  title: "Swagger Book Store"
host: "swagger.io"
basePath: "/v1"

schemes:
  - "https"
  - "http"
paths:
  /api/v1/book/{bookId}:
    get:
      tags:
        - "Book"
      summary: "Find Book by ID"
      description: "For valid response try integer IDs with value >= 1"
      operationId: "getBookById"
      produces:
        - "application/json"
      parameters:
        - name: "bookId"
          in: "path"
          description: "ID of pet that needs to be fetched"
          required: true
          type: "integer"
          maximum: 10.0
          minimum: 1.0
          format: "int64"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Book"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Order not found"
definitions:
  Book:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"

一個較正式且完整的文件範例:

API 系統實作：JavaScript、Python、Java 多語言範例

後端的 API 實作 其實不限制用什麼語言進行撰寫，各種語言撰寫上需要注意的觀念也大同小異，建議選擇熟悉的語言進行學習即可。本節將提供 JavaScript (Express.js)、Python (FastAPI) 和 Java (Spring Boot) 的多語言範例。

API 撰寫上有三個重點

1. 路徑: 包含版本、符合 REST 的規範
2. 輸入: 參數的各種類型
3. 輸出: 回傳格式

每個語言會有各自特性還有需要注意的觀念，底下會就小編的理解跟大家分享和解釋。

JavaScript API X Expressjs

1. 觀念:
   JavaScript 後端的實作語法概念跟前端其實並沒有太大的差異，觀念主要是單線程且 non-blocking 的設計，正常執行每一行程式時都不會卡住，所以大多都會搭配 Callback Function 進行處理。

2. Swagger:
   可能因為不是強型別，所以需要手工撰寫 OpenAPI 格式的 yaml 才能夠支援 Swagger。

3. 延伸閱讀:
   由於 Express 這類框架無法操作資料庫，所以將資料表示為 JavaScript 的 Object，再透過 ODM/ORM 工具去達到操作資料庫的目的，推薦透過 Mongoose 操作資料，只要三步驟就能打穿 MongoDB 到 API，ODM/ORM 通常能降低開發及維護成本，網站分成前跟後端而 Mongoose 也可以看成是 MongoDB 的前端介面。

範例程式碼:

1
2
3
4
5
6
7
8
9
10

const express = require("express");
const app = express();

app.get("/api/v1/book/:bookId", (req, res) => {
  res.json({ bookId: req.params.bookId });
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Python API X FastAPI

1. 觀念:
   打字打最少也最方便的一個語言，FastAPI 提供了方便快速開發的環境，透過自動產生文件與支援型別確認減少錯誤，官方文件表示能夠減少大約 40% 的人為錯誤。

2. Swagger:
   內建自動產生 openapi 的即時文件支援 Swagger、redoc，詳細說明可以參考這份文件: https://fastapi.tiangolo.com/#interactive-api-docs

3. 延伸閱讀:
   Python FastAPI 快速入門，7 行程式完成 API 和線上互動文件。

範例程式碼:

1
2
3
4
5
6
7
8

from fastapi import FastAPI
app = FastAPI()

@app.get('/api/v1/book/{bookId}')
def get_book_by_id(bookId: int):
    return {
        'bookId': bookId
    }

Java API X Springboot

1. 觀念:
   Java 後端的框架看來看去其實就是兩個觀念，Inversion of Control (IOC) 跟 Dependency Injection (DI)，控制反轉實作上會使用 @ 的方式來進行依賴注入。

2. Swagger:
   支援 Swagger 文件自動產生: https://www.baeldung.com/spring-rest-openapi-documentation

3. 延伸閱讀:
   Java Web API (RESTful API) 教學，三步驟打通關節開發 API 後端服務，主要會示範使用 Jersey 這套框架從 0 到 1 打造一個網站應用程式，並整理 Java Web Appication 相關資源如基礎建設、前端網頁、後端 Web API 及資料庫。

範例程式碼:

1
2
3
4
5
6
7
8
9
10
11
12
13

@SpringBootApplication
@RestController
public class DemoApplication {

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

  @GetMapping("/api/v1/book/{bookId}")
  public ResponseEntity<String> getBookById(@PathVariable String bookId) {
    return bookId.ok(bookId);
  }
}

FAQ：Web API 實作常見問題

Q1：我該選擇哪種語言開發後端 API？

A：這取決於團隊技術棧與專案需求。JavaScript (Express/Node.js) 適合 I/O 密集型且前後端共用語言的專案；Python (FastAPI) 開發速度快，適合資料科學或 AI 相關應用；Java (Spring Boot) 則以穩定性與強型別著稱，適合大型企業級系統。

Q2：一定要寫 Swagger/OpenAPI 文件嗎？

A：強烈建議。雖然手寫文件（如 Express）較繁瑣，但它能作為前後端溝通的「契約」，減少來回確認的時間。若使用 FastAPI 或 Spring Boot，通常能自動生成文件，更是事半功倍。

Q3：API 如何與資料庫連線？

A：現代開發通常透過 ORM (Object-Relational Mapping) 或 ODM 工具來操作資料庫，例如 Node.js 的 Mongoose/Sequelize、Python 的 SQLAlchemy、Java 的 JPA/Hibernate。這能讓開發者專注於物件操作，而非手寫複雜的 SQL 語句。

• ← 上一篇
• 下一篇 →