outofcoffee/imposter-openapi

Imposter：可编写脚本的多用途模拟服务器

Imposter 是一个可靠、可编写脚本且可扩展的模拟服务器，支持通用 REST API、https://github.com/OAI/OpenAPI-Specification%EF%BC%88%E5%8D%B3 Swagger）规范、Salesforce 和 HBase API。支持 JavaScript 或 Groovy/Java 脚本，可通过静态文件提供模拟响应，或使用脚本自定义行为（如状态码、响应文件等）。高级用户还可使用任意 JVM 语言编写自定义插件。

核心功能

• 从 OpenAPI/Swagger v2 和 OpenAPI v3 规范生成模拟端点
• 提供规范中嵌入的响应示例
• 可选验证 HTTP 请求是否符合 OpenAPI 规范
• 支持静态响应文件和脚本驱动的响应（状态码、响应文件等）

使用场景

• 独立运行模拟服务以替代真实系统
• 将 Swagger 文件转换为测试或 QA 用的模拟 API
• 为移动/Web 客户端团队快速搭建临时 API（在真实 API 开发期间）
• 解耦集成测试与云/后端系统，控制依赖项

Docker 部署示例

基本配置

创建配置文件 petstore-config.yaml：

yaml
# petstore-config.yaml
---
plugin: openapi
specFile: petstore.yaml

OpenAPI 规范文件示例

petstore.yaml 内容：

yaml
swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore"
consumes:
  - "application/json"
produces:
  - "application/json"
paths:
  /pets:
    get:
      description: "返回系统中的所有宠物"
      produces:
        - "application/json"
      responses:
        "200":
          description: "宠物列表"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
          examples:
            application/json: |-
              [
                {
                  "id": 101,
                  "name": "Cat"
                },
                {
                  "id": 102,
                  "name": "Dog"
                }
              ]
definitions:
  Pet:
    type: "object"
    required:
      - "id"
      - "name"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"

运行 Docker 容器

假设配置文件位于 ./docs/examples/openapi/simple 目录，执行以下命令启动模拟服务器：

bash
docker run --rm -ti -p 8080:8080 \
  -v $(pwd)/docs/examples/openapi/simple:/opt/imposter/config \
  outofcoffee/imposter-openapi

访问模拟服务

• 发送请求至定义的端点：curl http://localhost:8080/pets，将返回规范中定义的宠物列表示例。
• 访问交互式 API 沙箱：http://localhost:8080/_spec 查看端点详情。
• 停止服务：按 CTRL+C。

配置与使用

基本配置项

• plugin: 指定使用的插件（如 openapi）
• specFile: OpenAPI 规范文件路径
• validation.request: 是否启用请求验证（true/false）

请求验证

通过配置启用请求验证，确保请求符合 OpenAPI 规范：

yaml
# validating-request-config.yaml
---
plugin: "openapi"
specFile: "example-spec.yaml"

validation:
  request: true

启用后，无效请求将返回 HTTP 400 状态及验证错误详情（如缺失必填头信息、请求体不匹配 schema 等）。

覆盖响应状态码

通过 resources 配置自定义特定路径和方法的响应状态码：

yaml
# override-status-code-config.yaml
---
plugin: "openapi"
specFile: "spec-with-multiple-status-codes.yaml"

resources:
  - path: "/pets"
    method: "post"
    response:
      statusCode: 201

  - path: "/pets/:petId"
    method: "put"
    response:
      statusCode: 202

高级特性：脚本化响应

使用 JavaScript 或 Groovy 脚本控制响应行为，例如指定返回的示例名称、响应文件或内容：

脚本配置

yaml
# scripted-openapi-config.yaml
---
plugin: openapi
specFile: petstore.yaml
response:
  scriptFile: example.groovy

脚本示例（Groovy）

groovy
// 返回指定名称的示例
respond().withExampleName('dogExample')

// 返回静态文件内容
respond().withFile('some-file.json')

// 返回自定义内容
respond().withContent('{ "foo": "bar" }')

文档与示例

完整文档请参见：[***]

更多示例：

• docs/examples/openapi
• plugin/openapi/src/test/resources/openapi3/simple