Metadata-Version: 2.1
Name: specove
Version: 0.1.0a1
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.13
Classifier: Topic :: Documentation
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: browser
Requires-Dist: playwright <2,>=1.48 ; (python_version >= "3.9") and extra == 'browser'
Requires-Dist: uvicorn <1,>=0.22 ; (python_version >= "3.9") and extra == 'browser'
Provides-Extra: dev
Requires-Dist: setuptools >=67.8 ; extra == 'dev'
Requires-Dist: wheel >=0.42 ; extra == 'dev'
Requires-Dist: mypy ==1.4.1 ; extra == 'dev'
Requires-Dist: ruff ==0.8.6 ; extra == 'dev'
Requires-Dist: build ==0.10.0 ; (python_version < "3.8") and extra == 'dev'
Requires-Dist: pytest ==7.4.4 ; (python_version < "3.8") and extra == 'dev'
Requires-Dist: twine ==4.0.2 ; (python_version < "3.8") and extra == 'dev'
Requires-Dist: httpx <0.25,>=0.24 ; (python_version < "3.8") and extra == 'dev'
Requires-Dist: build <2,>=1 ; (python_version >= "3.8") and extra == 'dev'
Requires-Dist: pytest <10,>=8 ; (python_version >= "3.8") and extra == 'dev'
Requires-Dist: twine <7,>=6 ; (python_version >= "3.8") and extra == 'dev'
Requires-Dist: httpx <1,>=0.27 ; (python_version >= "3.8") and extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi <1,>=0.103.2 ; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: Flask <4,>=2.2.5 ; extra == 'flask'

# Specove

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

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

## 安装与接入

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

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

只使用哪个框架，就安装对应 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 验证；契约生成和完整规范验证仍由服务构建流程负责。

## 访问保护

- 默认读取 `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 仓库为私有。
