Scalar Django Ninja 集成scalar-ninja演进史与配置实战指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本文以仓库中 integrations/django-ninja/CHANGELOG.md 为脉络骨架结合 scalar_ninja.py 源码、tests 测试用例与 playground 示例工程完整梳理 Django Ninja 官方文档查看器如何与 Scalar API Reference 深度集成从 0.0.0 的重构起点到 0.3.0 的 Node.js 版本基线再到每一个 Minor/Patch 版本背后的技术动机同时系统讲解ScalarConfig、ScalarViewer、OpenAPISource、AgentConfig等核心配置对象与 30 项配置参数帮助你在 Django Ninja 项目中快速渲染出具备现代 REST API 客户端能力的交互式 API 文档。一、版本演进主线从重构到稳定发布的六个里程碑integrations/django-ninja/CHANGELOG.md完整记录了scalar-ninja包从诞生到 0.3.0 的全部版本历史。虽然 Changelog 只是逐条记录了变更但它恰好折射出该集成模块完整的技术演进轨迹可以归纳为六个关键里程碑版本类型核心变更技术含义0.0.0Minor重构 django-ninja 集成PR #7164模块化的起点确立了scalar_ninja包结构0.1.0Minor首次正式发布PR #7628发布到 PyPI对外可用0.1.1Patch更新文档域名PR #7810文档链接指向scalar.com官方域名0.1.2Patch新增 Agent Scalar 配置PR #8105引入AgentConfig支持全局与按源粒度控制 Agent Scalar0.2.0Minor修复servers结构严格遵循 OpenAPI 规范PR #8304servers参数改为符合 OpenAPI Server Object 的结构0.3.0Minor提升 Node.js 版本要求至 22LTSPR #8322构建与运行环境基线升级从这条主线可以读出两个重要信息一是 0.2.0 是唯一一次涉及 API 行为破坏性修正的版本servers数据结构变更二是 0.1.2 之后 Agent Scalar 能力成为配置体系的一等公民。接下来分别深入每个里程碑背后的源码事实。二、0.0.0 → 0.1.0重构与首次发布确立的包结构PR #7164commit85717a8将 django-ninja 集成重构为独立的scalar_ninja包这一结构沿用至今integrations/django-ninja/ ├── scalar_ninja/ # 核心 Python 包 │ ├── __init__.py # 公共 API 导出 │ ├── py.typed # PEP 561 类型标注标记 │ └── scalar_ninja.py # 全部实现枚举、配置模型、视图类 ├── tests/ # 单元测试 集成测试 ├── playground/ # 可运行的 Django 示例工程 ├── setup.py # 从 package.json 读取版本号 └── package.json # 版本单一来源0.3.0setup.py的实现细节值得注意包的版本号并非硬编码在 Python 侧而是通过get_version()读取同目录 package.json 中的version字段保证 JS 与 Python 两侧版本始终一致def get_version(): package_json_path os.path.join(os.path.dirname(__file__), package.json) with open(package_json_path, r) as f: package_data json.load(f) return package_data[version]0.1.0PR #7628是首次正式发布版本对应 PyPI 上的scalar-ninja包。scalar_ninja/__init__.py对外导出的公共 API 至今保持稳定ScalarViewer、ScalarConfig、OpenAPISource、AgentConfig以及Layout、Theme、SearchHotKey、DocumentDownloadType四个枚举。三、0.1.2 里程碑Agent Scalar 配置的引入PR #8105 引入了 Agent Scalar 配置能力这是 0.1.2 的核心内容。在源码中体现为新增的AgentConfigPydantic 模型位于 scalar_ninja.pyclass AgentConfig(BaseModel): Agent Scalar configuration. Use key for production, disabled to turn off. key: Optional[str] Field( defaultNone, descriptionAgent Scalar key for production. Required for production deployments., ) disabled: Optional[bool] Field( defaultNone, descriptionWhen True, disables Agent Scalar for this source or globally., ) model_config ConfigDict(extraforbid)该配置有两个字段语义清晰key生产环境必需的 Agent Scalar 密钥用于启用 Agent 能力disabled设置为True时关闭 Agent Scalar可作用于单个 OpenAPI 源或全局。AgentConfig在配置体系中出现了两个层级这一点在 tests/test_scalar_django_ninja.py 中有一一对应的测试用例顶层挂在ScalarConfig.agent上全局生效。test_top_level_agent_disabled验证了ScalarConfig(agentAgentConfig(disabledTrue))会被序列化为 JS 配置中的agent: {disabled: true}。按源粒度挂在OpenAPISource.agent上只对该 OpenAPI 文档生效。test_sources_with_per_source_agent验证了多源场景下每个 source 可携带独立的agent: {key: source-one-key}。在序列化端get_scalar_api_reference 中通过config.agent.model_dump(exclude_noneTrue)将 Pydantic 模型转换为 JS 可读的 JSONexclude_noneTrue保证None字段不会进入最终配置。四、0.2.0 里程碑servers 结构向 OpenAPI 规范对齐0.2.0PR #8304的变更描述非常值得细读fix: servers had the wrong structure documented, we adhere to the OpenAPI specification now这说明早期版本文档中对servers参数的结构描述有误0.2.0 将其修正为严格遵循 OpenAPI 规范的 Server Object 结构。在源码 scalar_ninja.py 中ScalarConfig.servers字段的类型标注与描述完整呈现了规范要求servers: List[Dict[str, Any]] Field( default_factorylist, descriptionList of OpenAPI Server Objects. Each item must have a required url (string) and may have optional description (string) and variables (map). Example: [{\url\: \https://api.example.com\, \description\: \Production\}]. Default is [] which means no servers are provided., )合规的servers结构依据 OpenAPI Server Objectservers[ {url: https://api.example.com, description: Production}, {url: http://localhost:8000, description: Development}, ]字段约束url必填服务器地址description可选服务器描述variables可选服务器变量映射表。测试 tests/test_scalar_django_ninja.py 的TestScalarConfig::test_with_servers与TestEdgeCases::test_servers_parameter均使用该结构断言序列化结果确认servers会被原样透传进Scalar.createApiReference的 JS 配置。升级注意如果你从早期版本迁移需要检查现有的servers写法是否符合{url: ..., description: ...}结构。五、0.3.0 里程碑Node.js 版本基线提升至 220.3.0PR #8322将运行环境要求提升为 Node.js 22LTS。这一约束在 package.json 中明确声明engines: { node: 22 }, version: 0.3.0, scripts: { dev: command -v python /dev/null 21 python manage.py runserver || echo ⚠️ python is not available, skipping the dev server., test: command -v python /dev/null 21 python run_tests.py || echo ⚠️ python is not available, skipping the tests. }对于使用者而言这一变更的实际影响是在本地开发、运行pnpm dev或执行测试脚本前需要保证 Node.js 版本不低于 22否则 npm/pnpm 会因engines约束给出警告或直接拒绝执行。而scripts中的dev/test也体现了该仓库的设计意图——Node 侧脚本只是对 Python 侧命令的薄封装真正的开发与测试仍由 Django/Python 完成。六、核心 API 实战三种配置方式全解析ScalarViewer是 Django Ninja 集成 Scalar 的入口类继承自ninja.openapi.docs.DocsBase可直接作为NinjaAPI的docs参数传入。其构造函数支持三种配置方式源码 scalar_ninja.py6.1 方式一关键字参数兼容旧版from scalar_ninja import ScalarViewer, Theme api NinjaAPI( titlePlayground API, version1.0.0, docsScalarViewer(themeTheme.KEPLER), )这是 playground_app/urls.py 中真实使用的写法。当只传 kwargs 时构造器会自动补上默认值openapi_url/api/openapi.json。6.2 方式二ScalarConfig 配置对象推荐类型安全from scalar_ninja import ScalarConfig, ScalarViewer, Theme, Layout config ScalarConfig( titleMy API, themeTheme.MOON, layoutLayout.CLASSIC, ) viewer ScalarViewer(configconfig)6.3 方式三混合传参kwargs 覆盖 configconfig ScalarConfig(titleOriginal Title, themeTheme.MOON) viewer ScalarViewer(configconfig, titleOverridden Title, themeTheme.PURPLE)此时 kwargs 中的同名参数会覆盖 config 对象中的值对应测试test_viewer_config_override。6.4 运行时渲染ScalarViewer只需实现render_page(request, api)方法即可接入 Django Ninja 的文档渲染流程。它委托给模块级函数get_scalar_api_reference(config)返回一个完整的 HTMLHttpResponse其中通过Scalar.createApiReference(#app, {...})初始化前端应用。整个渲染链路已被 tests/test_integration.py 的TestDjangoNinjaIntegration覆盖验证包括页面标题、OpenAPI URL、favicon、meta 标签等细节。七、ScalarConfig 全量配置参数速查表ScalarConfig是集成的配置中枢scalar_ninja.py所有字段均由 Pydantic 定义model_config ConfigDict(extraforbid)意味着传入未知字段会直接报错这为使用者提供了严格的类型保护。下表按功能分组整理全部参数默认值均来自源码与测试断言7.1 文档来源三选一优先级sources content openapi_url参数类型默认值说明openapi_urlstrNone兜底/api/openapi.jsonScalar 加载的 OpenAPI 文档 URLDjango Ninja 场景下通常自动指向/api/openapi.jsoncontentstr/dictNone直接传入 OpenAPI 文档内容JSON/YAML 字符串或字典sourcesList[OpenAPISource]None多 OpenAPI 文档源支持标题、slug、默认源等7.2 外观与主题参数类型默认值说明titlestrNone渲染为Scalar浏览器标签页标题layoutLayoutmodern布局modern/classicthemeThemedefault主题共 12 种可选值dark_modeboolNone初始暗色模式状态force_dark_mode_statestrNone强制锁定为dark或lighthide_dark_mode_toggleboolFalse隐藏暗色模式切换按钮show_sidebarboolTrue是否显示侧边栏hide_searchboolFalse是否隐藏侧边栏搜索框search_hot_keySearchHotKeyk搜索快捷键a-z 全部字母可用with_default_fontsboolTrue是否使用默认字体Inter 与 JetBrains Monocustom_cssstr附加的自定义 CSS 字符串scalar_favicon_urlstrhttps://django-ninja.dev/img/favicon.png浏览器标签页 faviconscalar_js_urlstrhttps://cdn.jsdelivr.net/npm/scalar/api-referenceScalar 前端脚本的加载地址CDNscalar_proxy_urlstrScalar Proxy 地址如https://proxy.scalar.com用于跨域请求转发Theme 枚举的 12 个可选值由测试test_theme_enum_all_values断言唯一性与数量default、alternate、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwave、none。7.3 内容展示行为参数类型默认值说明hide_modelsboolFalse隐藏全部模型Schemadefault_open_all_tagsboolFalse默认展开所有标签分组expand_all_model_sectionsboolFalse默认展开所有模型区块expand_all_responsesboolFalse默认展开所有响应区块order_required_properties_firstboolTrueSchema 对象中必填属性优先排序hide_test_request_buttonboolFalse隐藏「Test Request」按钮hide_client_buttonboolFalse隐藏侧边栏与弹窗中的客户端按钮hide_download_buttonboolFalse已废弃隐藏下载按钮建议改用document_download_typedocument_download_typeDocumentDownloadTypeboth下载文档类型json/yaml/both/none7.4 请求与网络行为参数类型默认值说明base_server_urlstr为所有相对服务器地址添加统一前缀serversList[Dict][]OpenAPI Server Object 列表0.2.0 起严格遵循规范hidden_clientsbool/dict/list[]按目标名隐藏对应客户端生成器authenticationdict{}附加认证信息支持 apiKey、oauth2 等复杂结构persist_authboolFalse将认证凭据持久化到本地存储7.5 扩展与 Agent参数类型默认值说明plugin_urlsList[str][]额外的 API Reference 插件ESM 模块地址integrationstrNone集成类型标识可覆盖默认值agentAgentConfigNone顶层 Agent Scalar 配置0.1.2 引入7.6 多源文档OpenAPISource 详解当需要在一个页面聚合多个 OpenAPI 文档时使用OpenAPISourcescalar_ninja.pyfrom scalar_ninja import OpenAPISource, ScalarConfig, ScalarViewer sources [ OpenAPISource(titleAPI 1, url/api1/openapi.json, defaultTrue), OpenAPISource(titleAPI 2, url/api2/openapi.json), OpenAPISource(titleAPI 3, content{openapi: 3.0.0, info: {title: Inline}}), OpenAPISource( titleAPI 4, url/api4/openapi.json, agentAgentConfig(keysource-specific-key), ), ] viewer ScalarViewer(configScalarConfig(sourcessources, titleMulti-API Docs))OpenAPISource字段说明titleAPI 显示名缺省时自动回退为API #1、API #2…slugURL 标识符缺省时由 title 或索引自动生成url与content二选一互斥分别对应外部文档地址与内联内容字符串或字典default多源场景下标记默认展示的源agent该源专属的 Agent Scalar 配置。注意ScalarConfig与OpenAPISource均设置了extraforbid任何拼写错误的字段都会在实例化时抛出 Pydantic 校验错误而非静默忽略——这是调试时最容易遇到的坑之一。八、底层原理get_scalar_api_reference 的配置序列化策略get_scalar_api_reference(config)scalar_ninja.py是渲染核心其设计策略有两点值得学习1. 只输出非默认值保持配置最小化。函数逐字段判断是否与默认值不同仅将差异项写入 JS 配置。例如layout默认是MODERN只有显式改为CLASSIC时才输出layout: classic。这一行为被test_default_parameters精确断言默认配置下proxyUrl、layout、showSidebar、theme等键都不应出现在 JS 配置中。好处是生成的 HTML 体积更小且前端升级新增默认项时无需修改集成代码。2. 完整 HTML 页面由 Python 端渲染。函数生成包含head标题、meta、favicon、内嵌主题 CSS与bodydiv idapp 脚本加载 Scalar.createApiReference(#app, {config})初始化调用的完整 HTMLhtml f !doctype html html head {ftitle{config.title if config.title else Scalar}/title} meta charsetutf-8/ meta nameviewport contentwidthdevice-width, initial-scale1 link relshortcut icon href{config.scalar_favicon_url} style...{scalar_theme if config.theme.value Theme.DEFAULT.value else }.../style /head body div idapp/div script src{config.scalar_js_url}/script script Scalar.createApiReference(#app, {json.dumps(js_config)}) /script /body /html 源码中还内嵌了一段scalar_themeCSS 变量主题scalar_ninja.py定义了明暗双模式下完整的--scalar-*颜色变量体系如--scalar-color-accent: #009485、--scalar-background-1、--scalar-sidebar-*等且仅在使用默认主题Theme.DEFAULT时注入让页面在无网络额外主题资源的情况下也能保持统一视觉风格。九、测试体系三层验证覆盖集成可靠性仓库在 tests 目录下提供了完备的测试可在无 Django 项目上下文的情况下独立运行测试文件覆盖范围代表性用例test_scalar_django_ninja.py枚举、配置模型、HTML 渲染、边界条件12 种主题唯一性、默认值全集断言、XSS 特殊字符标题、复杂 OAuth2 认证 JSONtest_integration.py与 Django Ninja 真实 API 的集成构建NinjaAPI 路由 Schema验证渲染出的页面结构与配置test_imports.py公共 API 导入完整性确保__init__.py导出无误run_tests.py测试入口一键执行全部测试运行方式仓库 package.json 中已封装pnpm --filter scalar-ninja test # 或直接 python run_tests.py测试中值得留意的细节test_integration.py构建了一个带GET /、GET /items/{item_id}、POST /items/的示例 API并通过 Django 的RequestFactory模拟请求验证了ScalarViewer.render_page返回 200 与正确的 HTML 结构——这正是你在真实项目中接入后应观察到的行为。十、动手实践运行 playground 示例工程仓库自带的 playground 是一个完整的 Django 示例应用其 playground_app/urls.py 中已经用docsScalarViewer(themeTheme.KEPLER)接入了 Scalar 文档视图。按 playground/README.md 即可本地运行pip install -r requirements.txt # 如环境为 pip3 请对应调整 python manage.py runserver随后访问http://127.0.0.1:8000/api/docs即可看到基于 Kepler 主题的交互式 API 文档OpenAPI JSON 则位于默认地址/api/openapi.json。示例中NinjaAPI定义了三个端点根路径、带路径参数的查询、带 Schema 的创建足以验证文档渲染、参数展示与「Test Request」交互能力。十一、使用注意事项与升级指引综合 CHANGELOG 与源码整理出以下实操提醒Node.js 版本0.3.0 起要求 Node 22LTS开发前先node --version确认servers 结构自 0.2.0 起必须使用 OpenAPI Server Object 结构url必填description/variables可选旧的非规范写法需要迁移下载按钮配置hide_download_button已标记废弃deprecated请改用document_download_type取值json/yaml/both/none源码中保留了对旧参数的后向兼容支持严格字段校验ScalarConfig、OpenAPISource、AgentConfig均设置了extraforbid字段拼写错误会在实例化阶段直接抛错善用类型提示与 IDE 补全可避免此类问题文档来源优先级同时传入sources、content、openapi_url时sources优先其次content最后openapi_url源码 scalar_ninja.py 中的判断顺序多源场景同一页面聚合多个 API 文档时为每个源设置title与default标记可显著提升导航体验。结语从 0.0.0 的重构到 0.3.0 的 Node.js 基线提升scalar-ninja的每一次版本迭代都对应着一个明确的技术决策类型安全的配置模型、OpenAPI 规范的严格对齐、Agent 能力的按源粒度控制。理解这些演进脉络不仅能帮你正确使用当前版本的全部能力也能在升级迁移时快速定位行为变化。结合本文的配置速查表与 playground 示例你可以在几分钟内为 Django Ninja 项目交付一套现代化的交互式 API 文档体验。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考