Aspire Api Reference Docker 镜像
scalarapi查看 Docker Hub 原文页
为.NET Aspire应用提供API参考文档的Scalar Docker镜像,用于生成、托管和展示API文档,支持OpenAPI规范解析与交互式文档浏览,简化API文档管理流程。
下载次数: 0状态:社区镜像维护者:scalarapi仓库类型:镜像最近更新:
Scalar API Reference Docker Image for Aspire
镜像概述
Scalar API Reference Docker Image for Aspire是Scalar API参考文档工具的Docker化版本,专为.NET Aspire应用生态系统设计。该镜像提供API文档生成、托管和交互展示的一站式解决方案,支持解析OpenAPI规范文件,生成可视化、可交互的API文档界面,帮助开发团队高效管理API文档资源。
核心功能与特性
- OpenAPI规范兼容:支持OpenAPI 2.0(Swagger)和OpenAPI 3.x规范,自动解析JSON/YAML格式的API定义文件
- 交互式文档界面:提供直观的Web界面,支持API端点检索、请求参数填写、响应示例预览及在线API调试
- .NET Aspire适配:优化支持.NET Aspire项目结构,可与Aspire服务发现机制集成,自动关联微服务API规范
- 容器化部署:轻量级Docker镜像设计,支持跨平台快速部署,降低文档服务搭建复杂度
- 自定义配置:通过环境变量灵活配置文档标题、描述、主题及logo,满足个性化文档需求
- 多端口与网络适配:支持自定义服务监听端口,适配不同网络环境下的端口映射需求
使用场景与适用范围
- .NET Aspire微服务项目:为基于Aspire构建的微服务架构提供统一API文档入口,聚合多服务API规范
- API开发协作:供前后端开发人员、测试人员查阅API详情,减少接口沟通成本
- CI/CD流程集成:嵌入持续集成/部署 pipeline,实现API文档的自动更新与版本管理
- 对外API门户:作为对外提供API服务的官方文档站点,展示API功能、使用方法及权限说明
使用方法与配置说明
前提条件
- Docker Engine 20.10+ 环境
- API规范文件(OpenAPI JSON/YAML格式)或已启用OpenAPI生成的.NET Aspire应用
快速启动(docker run)
通过以下命令启动容器,托管本地API规范文件:
bashdocker run -d \ --name aspire-api-docs \ -p 8080:80 \ -v /local/path/to/openapi:/app/specs \ -e SCALAR_API_SPEC=/app/specs/aspire-api.openapi.yaml \ -e SCALAR_TITLE="Aspire Project API Docs" \ -e SCALAR_THEME=dark \ docker.xuanyuan.run/scalar/aspire-api-reference:latest
参数说明:
-p 8080:80:将容器内80端口映射至主机8080端口,通过http://localhost:8080访问文档-v /local/path/to/openapi:/app/specs:挂载本地API规范文件目录至容器内/app/specs-e SCALAR_API_SPEC:指定容器内API规范文件路径(支持单个文件或目录批量加载)-e SCALAR_TITLE:设置文档页面标题
环境变量配置
| 环境变量名 | 描述 | 默认值 |
|---|---|---|
SCALAR_API_SPEC | API规范文件在容器内的路径/目录 | /app/openapi.yaml |
SCALAR_PORT | 容器内服务监听端口 | 80 |
SCALAR_TITLE | 文档页面主标题 | Scalar API Reference |
SCALAR_DESCRIPTION | 文档页面副标题/描述 | Automatically generated API documentation |
SCALAR_THEME | 界面主题(支持light/dark/auto) | light |
SCALAR_LOGO | 自定义logo图片URL(建议SVG/PNG格式) | Scalar默认logo |
SCALAR_DEFAULT_SERVER | 默认API服务器地址(用于在线调试) | http://localhost |
Docker Compose配置示例
在.NET Aspire项目中集成文档服务的docker-compose.yml示例:
yamlversion: '3.8' services: api-docs: image: docker.xuanyuan.run/scalar/aspire-api-reference:latest container_name: aspire-api-docs ports: - "8080:80" volumes: - ./src/AspireApiService/OpenApi:/app/specs # 挂载Aspire服务生成的OpenAPI文件 environment: - SCALAR_API_SPEC=/app/specs/v1/openapi.yaml - SCALAR_TITLE=Aspire E-commerce API Docs - SCALAR_DESCRIPTION=API Documentation for E-commerce Microservices - SCALAR_THEME=dark - SCALAR_DEFAULT_SERVER=http://api-service:5000 depends_on: - api-service # 依赖Aspire API服务(确保API规范文件已生成) restart: unless-stopped
与.NET Aspire集成要点
-
启用Aspire OpenAPI生成:在Aspire项目中为目标服务配置OpenAPI生成
csharp// 在Program.cs中配置Aspire服务 var builder = DistributedApplication.CreateBuilder(args); var apiService = builder.AddProject<Projects.Ecommerce_Api>("api-service") .WithOpenApi(openApi => { openApi.WithTitle("E-commerce API") .WithVersion("v1") .WithDescription("Core e-commerce microservice API"); }); -
挂载Aspire生成的OpenAPI文件:Aspire默认将OpenAPI规范文件输出至
./src/[ServiceName]/bin/[Configuration]/[Framework]/OpenApi目录,可通过Docker volume挂载该路径
注意事项
- API规范格式校验:确保挂载的OpenAPI文件符合规范要求,可通过https://validator.swagger.io/提前校验
- 生产环境安全:建议通过反向代理(如Nginx)配置访问控制(如Basic Auth),限制文档访问权限
- 高可用部署:多实例部署时需确保API规范文件同步,或通过共享存储(如NFS)挂载规范文件目录
- 版本兼容性:使用与Aspire版本匹配的Scalar镜像,避免因API规范版本差异导致解析异常
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。
轩辕镜像加速拉取命令点我查看更多 aspire-api-reference 镜像标签
docker pull docker.xuanyuan.run/scalarapi/aspire-api-reference:<标签>
DockerHub 原生拉取命令
docker pull scalarapi/aspire-api-reference:<标签>
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务