Metadata-Version: 2.1
Name: specove
Version: 0.1.0a4
Summary: 轻量、离线、多消费方与多版本的 OpenAPI 文档浏览组件
License: MIT License
        
        Copyright (c) 2026 deepaint-ai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/deepaint-ai/specove
Keywords: openapi,swagger,flask,fastapi,offline,documentation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: flask
Provides-Extra: fastapi
Provides-Extra: browser
Provides-Extra: dev
License-File: LICENSE

# 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。

## 安装与接入

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

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

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

```python
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 使用同样的注册参数：

```python
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 不会替换它们。

## 文档目录

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

`catalog.json` 示例：

```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/。使用项目自身虚拟环境：

```console
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 仓库为私有。
