本文適合讀者

• 編程新手及中級者
• 對 API 基礎有所瞭解的人士
• 想快速通過 OpenAPI 嘗試 Mock 服務器的人

本文目的

• 指導讀者建立模擬服務器環境
• 探索 Swagger 的使用方法
• 學習如何使用 OpenAPI 編制特定的 API 設計

OpenAPI概述

官方文檔描述如下：

OpenAPI規範（原稱Swagger規範）是一種用於REST API的API描述格式。

簡而言之，OpenAPI 文檔可以通過 YAML 或 JSON 格式詳細描述 API 的全貌，包括：

• 可用的端點（如/user）及其操作（如GET /users, POST /users）
• 參數操作和輸入/輸出格式
• 身份驗證方法

Swagger 簡介

Swagger 提供了一套用於通過OpenAPI框架設計 REST API 的工具。包括以下工具：

Prism快速瞭解

Prism 提供的 API 模擬和合同測試能力，支持 OpenAPI v2（即Swagger）和 OpenAPI v3.x版本。Prism 的主要功能包括：

1. 模擬服務器創建：基於任何 API 規範文檔生成逼真的模擬服務器。
2. 驗證代理：允許 API 消費者和開發者進行合同測試。
3. 全面支持 API 規範：支持 OpenAPI v3.1、v3.0，v2.0（即Swagger）以及 Postman 集合。

Prism幫助開發者更好地測試和調試 API，確保遵循規範。此外，它還為前端開發人員提供了模擬API的便利，使他們在實際 API 完成之前就能開始工作，有效地連接了開發流程。

Prism快速入門

安裝Prism

yarn global add @stoplight/prism-cli

curl -L https://raw.githack.com/stoplightio/prism/master/install | sh

啓動 Mock 服務

prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml

驗證服務狀態

通過使用模擬服務器，可以輕鬆測試與 OpenAPI 數據交換，無需建立服務器端環境，非常方便。

在 Nextjs 中集成 Swagger 文檔

import { GetStaticProps, InferGetStaticPropsType } from 'next';
import { createSwaggerSpec } from 'next-swagger-doc';
import dynamic from 'next/dynamic';
import 'swagger-ui-react/swagger-ui.css';
const SwaggerUI = dynamic<{spec: any;}>(import('swagger-ui-react'), { ssr: false });
function ApiDoc({ spec }: InferGetStaticPropsType<typeof getStaticProps>) {
    return <SwaggerUI spec={spec} />;
}
export const getStaticProps: GetStaticProps = async () => {
    const spec = createSwaggerSpec({definition: {
        openapi: '3.0.0',
        info: {title: 'Next Swagger API 示例', version: '1.0',},
    },});
    return { props: { spec, }, };
};

export default ApiDoc;

設置next-swagger-doc.json

{
  "apiFolder": "pages/api",
  "schemaFolders": ["models"],
  "definition": {
    "openapi": "3.0.0",
    "info": {
      "title": "Next Swagger API 示例",
      "version": "1.0"
    }
  }
}

生成doc.json

yarn next-swagger-doc-cli next-swagger-doc.json

其他方法

利用此配置文件，您可以將 prism 與前端項目文檔（如next-swagger-doc.json）結合使用，為項目提供API端點，確保開發不會延遲。對於覺得搭建服務器有難度的人，Apifox 提供了一個有效的選擇。

Apifox 不僅方便 Mock數據 創建，還提供了前置操作、後置操作、持續集成、代碼生成等功能，支持自定義規則和手寫 mockjs 腳本等高級設置，因此，許多人利用 Apifox 的免費 Mock 功能快速生成和管理 Mock 數據。