跳到主要内容
版本:3.9.x

定制开发者门户

本指南介绍如何基于 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。请确保开发者门户能够访问此端点。

config.yaml
portal:
url: ${PORTAL_URL}
token: ${PORTAL_TOKEN}

创建门户 Token

  1. 登录 API7 企业版控制台,切换至 API7 提供者门户。
  2. 打开 开发者门户设置。
  3. 生成用于访问 API 的 Token。
  4. 复制 Token,格式为 a7prt-xxxxxxxxxxxx。

应用程序设置​

config.yaml
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。

示例:定制主色

globals.css
:root {
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
}

可用的主题变量见模板仓库中的 globals.css 文件。

身份认证​

模板使用 Better Auth 进行身份认证。

电子邮件和密码​

此配置控制用户注册和登录时使用的电子邮件和密码认证。

config.yaml
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 提供商。

config.yaml
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 仓库。也可以在模板仓库中查看实际用法示例。

其他资源​