Specove

轻量、离线的 OpenAPI 文档浏览组件。读取现有 catalog，按消费方、API 系列、文档版本和生命周期展示文档。页面由包内固定版本的 Swagger UI 渲染，不依赖 CDN，不要求使用者安装 Node.js。

当前版本：0.1.0a4（Alpha 预览版）。支持 Python 3.7–3.14、Flask 和 FastAPI；最低环境使用 Flask 2.2.5 / FastAPI 0.103.2 起的兼容版本，不代表最新框架支持 Python 3.7。

安装与接入

按使用框架选择对应的安装方式：

python -m pip install "specove[flask]==0.1.0a4"
python -m pip install "specove[fastapi]==0.1.0a4"

只使用哪个框架，就安装对应 extra。框架无关的核心没有第三方运行依赖。

from pathlib import Path
from flask import Flask
from specove.flask import register_docs

root = Path(__file__).resolve().parent
app = Flask(__name__)
viewer = register_docs(
    app,
    docs_dir=root / "docs/openapi",
    project_root=root,
)

FastAPI 使用同样的注册参数：

from pathlib import Path
from fastapi import FastAPI
from specove.fastapi import register_docs

root = Path(__file__).resolve().parent
app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
viewer = register_docs(
    app,
    docs_dir=root / "docs/openapi",
    project_root=root,
)

访问 /doc/，HTTP Basic 用户名默认 docs。宿主自行决定是否在 development/testing 注册；Specove 不判断服务环境，不修改原有路由或业务鉴权。FastAPI 原生 /docs、/redoc、/openapi.json 由宿主决定是否关闭，Specove 不会替换它们。

文档目录

docs/openapi/
├── catalog.json
├── .specove-password
└── service/v1.0.0/openapi.json

catalog.json 示例：

{
  "format_version": 1,
  "api_version": "v1",
  "documents": [
    {
      "consumer": "service",
      "title": "内部服务",
      "api_version": "v1",
      "document_version": "v1.0.0",
      "path": "docs/openapi/service/v1.0.0/openapi.json",
      "lifecycle": "workspace-snapshot",
      "operation_count": 1
    }
  ]
}

path 相对于 project_root，必须解析到 docs_dir 内。只展示目录声明的条目，不扫描历史文件、不要求 all 目录；目录按注册时的快照展示，更新目录后需重建应用。OpenAPI JSON 在读取时重新校验。

首版展示 OpenAPI 3.0.x、3.1.x 自包含 JSON，仅支持 JSON Pointer 内部引用；拒绝外部引用和目录越界。不宣称完成完整 OpenAPI Schema 验证；契约生成和完整规范验证仍由服务构建流程负责。

自动维护目录说明

实际注册时，Specove 在调用方传入且已经存在的 docs_dir 内维护 SPECOVE.md。 缺失时生成，文档规范版本变化时原子更新；同规范版本不因工具升级重写。 文件明确标注规范版本、生成工具版本和“请勿修改”的提示，项目补充约定请另建文件。 内容包括目录结构、catalog 字段及示例、最小 OpenAPI 文档、凭据保护及 AI 迁移指引。 说明在目录内容校验前生成，便于校验失败时参考；生成失败仅记录警告，不放宽原有校验。 不存在的目录不会被创建；未调用 Specove（如 CommonLib production 模式）没有生成行为。 本功能不修改 catalog、接口文档或宿主 Git 配置，不通过 HTTP 暴露说明文件。

访问保护

• 默认读取 docs_dir/.specove-password；不存在才原子生成，后续重启/多 worker 复用。
• password="明确指定的密码" 使用指定值，不接触旧文件；移除指定值后恢复使用旧文件。
• allow_anonymous=True 显式允许匿名，不创建密码文件；不能同时指定密码。
• 空白密码、损坏/不可读文件或无法保存均报错，不自动覆盖或开放匿名。
• 可用 password_file=绝对路径 覆盖存储位置，url_prefix="/internal/doc" 改变文档路由。
• 管理员可受控读取文件，或使用注册返回的 viewer.password；不要打印到普通日志、公开接口或错误页。文件保存可恢复的密码原文，必须按凭据保护。
• 首次创建依赖文件系统支持原子硬链接；不支持时明确报错，可显式配置密码，不退回竞态写入。
• 将 **/.specove-password 加入宿主 Git 忽略及文档交付排除规则；自定义密码文件名也要排除。Specove 不改写宿主仓库。
• Specove 不提供任意目录静态服务；宿主其它静态目录、反向代理也不得暴露密码文件。HTTP Basic 通过 HTTPS 使用。

页面、目录、JSON 和固定资源都受同一认证保护。默认关闭在线 API 调用和外部校验，浏览器只加载当前目录的本地资源。支持前缀与代理挂载；转发头的信任由宿主配置。

开发与发布

测试在 test/，全部缓存与临时产物在 tmp/。使用项目自身虚拟环境：

python -m pip install ".[dev,flask,fastapi]"
python -m ruff format --check src test
python -m ruff check src test
python -m mypy
python -m pytest
python -m build
python test/check_artifacts.py
python -m twine check dist/*

发行包只包含必要的用户说明与许可，不包含 docs/ 下的开发设计、交接或发布过程文档；这些资料仅供源码仓库维护使用。

Specove 采用 MIT；固定版本 Swagger UI 保留独立 Apache-2.0 许可，来源和校验值随包记录。公开 PyPI 的源码和资源公开，即使 GitHub 仓库为私有。