如何在Stoplight Prism mock服务器中提供静态内容服务

Stoplight Prism 4 核心定位是API Mock服务，原生没有内置静态文件托管能力，无法直接通过内置配置挂载静态资源路径，但可以通过两种轻量方案实现/static/doc.html路径访问静态文档的需求，不需要额外维护独立的Web服务，和现有/api/路径下的Mock接口完全兼容。

方案1：自定义镜像叠加Nginx路由分流（团队使用首选，零侵入） #

基于官方stoplight/prism:4镜像做二次构建，加一层轻量Nginx做路由转发，对外只暴露一个服务端口，逻辑清晰维护成本低：

• /api/* 路径的请求全部转发给本地Prism进程处理Mock逻辑
• /static/* 路径的请求直接由Nginx返回本地存储的静态HTML及关联资源

实现步骤 #

1. 准备自定义Dockerfile

# 复用官方Prism镜像的二进制文件
FROM stoplight/prism:4 as prism
FROM nginx:alpine
COPY --from=prism /usr/local/bin/prism /usr/local/bin/prism

# 复制本地OpenAPI描述文件到容器内
COPY ./your-openapi-spec.yaml /app/openapi.yaml
# 复制静态API文档到Nginx静态目录，对应/static/doc.html访问路径
COPY ./doc.html /usr/share/nginx/html/static/doc.html
# 复制Nginx配置和启动脚本
COPY nginx.conf /etc/nginx/nginx.conf
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

EXPOSE 80
ENTRYPOINT ["/entrypoint.sh"]

2. 编写核心路由配置nginx.conf

events {
    worker_connections 1024;
}
http {
    server {
        listen 80 default_server;
        # 静态资源路径直接返回本地文件
        location /static/ {
            root /usr/share/nginx/html;
            default_type text/html;
            add_header Access-Control-Allow-Origin *;
        }
        # API Mock路径转发给本地Prism服务
        location /api/ {
            proxy_pass http://127.0.0.1:4010;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

3. 编写启动脚本entrypoint.sh，同时拉起Prism和Nginx进程

#!/bin/sh
# 后台启动Prism Mock服务，仅监听本地回环地址，API前缀匹配/api路径
prism mock -h 127.0.0.1 -p 4010 --cors /app/openapi.yaml &
# 前台启动Nginx承接外部流量
nginx -g 'daemon off;'

构建镜像启动后，原有/api/*下的Mock接口完全不受影响，直接访问http://<服务地址>/static/doc.html即可打开API参考文档。如果后续文档需要关联CSS、JS等其他静态资源，直接放到/usr/share/nginx/html/static/对应目录下即可，不需要额外改配置。

方案2：Prism请求钩子拦截返回（单文件极简场景适用） #

如果仅需要托管单个HTML文件、不想引入Nginx，可以利用Prism的请求生命周期钩子，拦截指定路径的请求直接返回静态内容：

1. 编写钩子文件hooks.js，读取本地HTML文件内容

const fs = require('fs');
const docHtml = fs.readFileSync('./doc.html', 'utf-8');

module.exports = {
  request: {
    beforeRoute(req, res) {
      // 匹配静态文档路径直接返回内容
      if (req.url.pathname === '/static/doc.html') {
        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
        res.end(docHtml);
        return;
      }
    }
  }
}

2. 启动Prism时加载钩子文件即可

prism mock -h 0.0.0.0 -p 4010 --cors --hooks ./hooks.js your-openapi-spec.yaml

如果使用官方Docker镜像启动，只需要把OpenAPI文件、钩子文件、HTML文档挂载进容器，修改启动命令加上--hooks ./hooks.js参数即可生效。

注意：该方案仅适合单文件场景，如果需要托管多个静态资源，每个路径都需要单独写拦截逻辑，维护成本远高于方案1。

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