如何在浏览器端（React+Cypress）基于OpenAPI规范验证请求？

不用搭建后端或Mock Server，你可以通过支持浏览器环境的OpenAPI验证库结合Cypress的请求拦截能力实现需求，以下是两种可行的实现方式：

方案一：AJV + JSON Schema Ref Parser（轻量灵活） #

AJV是一款高性能的JSON Schema验证库，支持浏览器环境；JSON Schema Ref Parser可以解析OpenAPI规范中的$ref引用，将Schema扁平化，方便AJV验证。

步骤1：引入依赖 #

在Cypress的support/index.js中引入兼容浏览器的库版本：

import Ajv from 'ajv/dist/ajv.min.js';
import { dereference } from '@apidevtools/json-schema-ref-parser/dist/ref-parser.min.js';
import jsYaml from 'js-yaml/dist/js-yaml.min.js';

步骤2：编写Cypress自定义命令 #

创建一个通用的验证命令，用于加载OpenAPI规范、解析Schema并验证请求：

Cypress.Commands.add('validateRequestAgainstOpenAPI', (request, specFixturePath) => {
  // 加载OpenAPI规范文件（放在cypress/fixtures目录下）
  cy.fixture(specFixturePath).then(specYaml => {
    // 将YAML格式的规范转为JSON
    const openApiSpec = jsYaml.load(specYaml);
    
    // 解析所有$ref引用，生成扁平化的Schema
    dereference(openApiSpec).then(dereferencedSpec => {
      // 匹配请求对应的路径和方法的Schema
      const requestPath = request.url.replace(Cypress.config('baseUrl'), '');
      const pathSchema = dereferencedSpec.paths[requestPath]?.[request.method.toLowerCase()];
      
      if (!pathSchema) {
        throw new Error(`OpenAPI规范中未找到 ${request.method} ${requestPath} 的定义`);
      }

      const ajv = new Ajv({ coerceTypes: true });

      // 验证请求Query参数
      if (pathSchema.parameters?.some(p => p.in === 'query')) {
        const querySchema = {
          type: 'object',
          properties: pathSchema.parameters
            .filter(p => p.in === 'query')
            .reduce((acc, param) => {
              acc[param.name] = param.schema;
              return acc;
            }, {}),
          required: pathSchema.parameters
            .filter(p => p.in === 'query' && p.required)
            .map(p => p.name)
        };
        const isValid = ajv.validate(querySchema, request.query);
        if (!isValid) {
          throw new Error(`Query参数验证失败：${ajv.errorsText()}`);
        }
      }

      // 验证请求Body
      if (pathSchema.requestBody) {
        const bodySchema = pathSchema.requestBody.content['application/json']?.schema;
        if (bodySchema) {
          const isValid = ajv.validate(bodySchema, request.body);
          if (!isValid) {
            throw new Error(`请求Body验证失败：${ajv.errorsText()}`);
          }
        }
      }
    });
  });
});

步骤3：在测试中使用 #

拦截请求后调用自定义命令验证：

it('验证创建用户请求符合OpenAPI规范', () => {
  cy.intercept('POST', '/api/users').as('createUser');
  
  // 触发创建用户的操作
  cy.get('[data-testid="create-user-btn"]').click();
  
  cy.wait('@createUser').then(interception => {
    // 传入拦截到的请求和OpenAPI规范的fixture路径
    cy.validateRequestAgainstOpenAPI(interception.request, 'openapi.yaml');
  });
});

方案二：Stoplight Spectral（全量规范验证） #

Spectral是专门用于验证API规范的工具，支持浏览器环境，不仅能验证Schema，还能检查请求是否符合OpenAPI的风格、规则要求。

步骤1：引入依赖 #

import { Spectral } from '@stoplight/spectral/dist/spectral.min.js';
import { openApi } from '@stoplight/spectral-rulesets/dist/rulesets/openapi.min.js';
import jsYaml from 'js-yaml/dist/js-yaml.min.js';

步骤2：编写Cypress命令 #

Cypress.Commands.add('validateRequestWithSpectral', (request, specFixturePath) => {
  cy.fixture(specFixturePath).then(specYaml => {
    const openApiSpec = jsYaml.load(specYaml);
    const spectral = new Spectral();
    
    // 加载OpenAPI官方规则集
    spectral.setRuleset(openApi);
    
    // 构造Spectral需要的请求格式
    const spectralRequest = {
      method: request.method.toLowerCase(),
      path: request.url.replace(Cypress.config('baseUrl'), ''),
      body: request.body,
      query: request.query
    };
    
    // 执行验证
    spectral.run({ ...openApiSpec, request: spectralRequest }).then(results => {
      if (results.length > 0) {
        throw new Error(`请求验证不通过：${JSON.stringify(results, null, 2)}`);
      }
    });
  });
});

步骤3：测试中调用 #

it('用Spectral验证请求合规性', () => {
  cy.intercept('GET', '/api/users').as('getUsers');
  cy.get('[data-testid="load-users-btn"]').click();
  
  cy.wait('@getUsers').then(interception => {
    cy.validateRequestWithSpectral(interception.request, 'openapi.yaml');
  });
});

注意事项 #

• 若OpenAPI规范包含外部$ref，建议提前用NodeJS工具（如json-schema-ref-parser）将规范扁平化，生成无引用的JSON文件，再放到Cypress的fixtures目录，减少浏览器端的解析耗时。
• 确保引入的库均为浏览器兼容版本，避免使用仅支持NodeJS的包。

内容的提问来源于stack exchange，提问作者Maddin