从零开始：如何快速建立 Swagger Mock 服务器

本文适合读者

• 编程新手及中级者
• 对 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 数据。