定制开发者门户
本指南介绍如何基于 API7 开发者门户模板定制 开发者门户。
概述
API 门户包含可定制的开发者门户,供开发者发现和使用 API。API7 提供开源开发者门户模板作为基础,其中包含以下组件和功能。
内置组件
- 基于 Next.js 构建,前端工程师可以使用熟悉的技术栈。
- 采用 Better Auth 构建的完整用户管理系统。
- 集成 @api7/portal-sdk 以调用 API 门户的 API。
内置功能
- 电子邮件和密码认证,可启用单点登录。
- 展示 API 产品并渲染其 OpenAPI 文档。
- 支持使用
Try it Out测试 API。 - 支持创建应用程序和凭证。
- 支持通过 DCR 协议与身份提供商集成。
前端工程师可以按需定制和扩展该模板。
更多详情请参阅模板仓库。
配置
所有配置均通过 apps/site/config.yaml 管理。将 config.yaml.example 复制为该文件,再按所在环境修改。配置支持以下环境变量替换语法。
| 语法 | 行为 |
|---|---|
${VAR} | 必填。如果未设置 VAR,则报错。 |
${VAR:default} | 选填。如果未设置 VAR,则使用 default。 |
连接 API 门户后端
开发者门户连接 API 门户的后端 API。请确保开发者门户能够访问此端点。
portal:
url: ${PORTAL_URL}
token: ${PORTAL_TOKEN}
创建门户 Token
- 登录 API7 企业版控制台,切换至 API7 提供者门户。
- 打开 开发者门户设置。
- 生成用于访问 API 的 Token。
- 复制 Token,格式为
a7prt-xxxxxxxxxxxx。
应用程序设置
app:
name: "Your Developer Portal" # 显示在浏览器标题和页眉中
desc: "Your portal description" # 用作 SEO 元描述
baseURL: "https://your-portal.example.com" # 用于生成链接和 SEO 的公开 URL
trustedOrigins: # CORS 和身份认证回调允许的来源
- "https://your-portal.example.com"
品牌定制
本节的改动需要重新构建并部署应用程序后才会生效。修改 config.yaml 后,需要重启应用程序。
标志和资源
将以下文件替换为你的组织使用的资源。
| 文件 | 位置 | 用途 |
|---|---|---|
| 站点图标 | apps/site/app/favicon.ico | 浏览器标签页图标 |
| 标志 | apps/site/public/logo.svg | 页眉标志 |
定制主题
编辑 apps/site/app/globals.css,定制颜色和样式。门户使用 Tailwind CSS、Shadcn UI 和 Ant Design。
示例:定制主色
:root {
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
}
可用的主题变量见模板仓库中的 globals.css 文件。
身份认证
模板使用 Better Auth 进行身份认证。
电子邮件和密码
此配置控制用户注册和登录时使用的电子邮件和密码认证。
auth:
emailAndPassword:
enabled: true
requireEmailVerification: false
Better Auth 没有内置电子邮件服务集成。要启用电子邮件验证,需要在 apps/site/src/lib/auth/server.ts 中集成你选择的电子邮件服务提供商 SDK。在未集成服务的情况下设置 requireEmailVerification: true,不会发送任何邮件。更多详情请参阅 Better Auth 电子邮件文档。
单点登录集成
Better Auth 支持集成 GitHub 和 Google 等常见 OAuth 提供商。
auth:
socialProviders:
github:
clientId: ${GITHUB_CLIENT_ID}
clientSecret: ${GITHUB_CLIENT_SECRET}
google:
clientId: ${GOOGLE_CLIENT_ID}
clientSecret: ${GOOGLE_CLIENT_SECRET}
对于企业身份提供商,可以配置通用 OAuth 插件。你需要修改 apps/site/src/lib/auth/server.ts 中的代码。更多详情请参阅 Better Auth OAuth 文档。
扩展门户
模板提供以下扩展点,可用于定制开发。
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 页面 | apps/site/app/ | 添加或修改 Next.js 页面 |
| 组件 | apps/site/components/ | 定制界面组件 |
| 身份认证逻辑 | apps/site/src/lib/auth/ | 定制身份认证 |
| API 路由 | apps/site/app/api/ | 定制后端端点 |
有关高级定制方式,请参阅 Next.js 和 Better Auth 文档。
Portal SDK
Portal SDK(@api7/portal-sdk)提供用于调用 API 门户后端 API 的 TypeScript 客户端。模板已集成此 SDK,也可单独使用它开发定制集成。
安装
npm install @api7/portal-sdk
服务器端使用
适用于后端应用程序或 BFF(面向前端的后端)。
import { API7Portal } from '@api7/portal-sdk'
const client = new API7Portal({
endpoint: 'https://api7-portal-api.example.com', // API 门户后端 API URL
token: 'a7prt-...',
getDeveloperId: async () => await getDeveloperIdFromSession(),
});
const products = await client.apiProduct.list();
客户端使用
适用于通过 BFF 代理访问后端的浏览器应用程序。
import { API7Portal } from '@api7/portal-sdk/browser'
const client = new API7Portal();
const products = await client.apiProduct.list();
完整的 SDK 文档和可用 API 见 Portal SDK 仓库。也可以在模板仓库中查看实际用法示例。