Open API Guide

`/api` 现在展示为文档界面，而不是原始 JSON 数据。

这里集中展示 OAuth 流程、管理端接口、示例请求与响应格式，并保留在线调试能力，方便前后端联调和第三方系统接入。

开始调试查看 OAuth 流程

Base URL

/

OAuth 标准接口为公开端点，管理类接口以 /api/... 形式提供。

Authentication

Session Cookie Bearer Token RBAC 权限控制

管理后台 API 需要登录后访问；OAuth 用户信息接口使用 Bearer Token 鉴权。

OAuth Endpoints

核心授权接口

3 个公开端点

GET /oauth/authorize

用于发起 OAuth 2.0 授权码流程，成功后会重定向至业务系统的回调地址。

关键参数

client_id：客户端 ID
redirect_uri：回调地址
response_type=code
scope、state

示例

/oauth/authorize?client_id=web-demo&redirect_uri=https%3A%2F%2Fdemo.app%2Fcallback&response_type=code&scope=read%20write&state=random_state

POST /oauth/token

根据 grant_type 获取访问令牌，支持授权码模式与客户端凭证模式。

支持的模式

authorization_code
client_credentials

请求头

Content-Type: application/x-www-form-urlencoded

GET /oauth/userinfo

通过 Bearer Token 获取已授权用户的资料信息。

请求头

Authorization: Bearer {access_token}

成功响应字段

{
  "id": "user-id",
  "username": "admin",
  "email": "admin@example.com"
}

OAuth Flow

接入流程说明

/api 页面仅展示对外 OAuth 接入能力，不再公开后台管理接口，避免暴露内部管理边界。

发起授权

业务系统将用户重定向到 /oauth/authorize，携带 client_id、redirect_uri 等参数。

交换令牌

获取授权码后，请求 /oauth/token 交换访问令牌，或使用客户端凭证模式直接换取令牌。

获取用户信息

拿到访问令牌后，调用 /oauth/userinfo 完成用户身份获取与登录态建立。

Interactive Debugger

在线调试

保留原有在线调试能力，你可以直接在文档页填写参数并测试令牌获取、用户信息查询等流程。

GET /oauth/authorize

Client ID

Redirect URI

Scope