优化开放 API 文档界面

frontend/src/openapi/endpoints.ts

@@ -152,6 +152,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'list-products',
     method: 'GET',
     path: '/api/client/v1/products',
+    title: '商品列表',
     summary: '查询商户已授权且上架的商品列表',
     scope: 'products:read',
     queryParams: [
@@ -196,6 +197,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'create-order',
     method: 'POST',
     path: '/api/client/v1/orders',
+    title: '创建订单',
     summary: '幂等创建订单并扣款（成功返回 201，重复请求返回 200 且 idempotent=true）',
     scope: 'orders:write',
     bodyParams: [
@@ -240,6 +242,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'query-order',
     method: 'GET',
     path: '/api/client/v1/orders/{order_no}',
+    title: '查询订单',
     summary: '查询订单状态与详情',
     scope: 'orders:read',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -250,6 +253,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'cancel-order',
     method: 'POST',
     path: '/api/client/v1/orders/{order_no}/cancel',
+    title: '取消订单',
     summary: '取消未履约订单并退款（仅 pending/failed 可取消）',
     scope: 'orders:write',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -266,6 +270,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'delivery-link',
     method: 'GET',
     path: '/api/client/v1/orders/{order_no}/delivery-link',
+    title: '获取发货链接',
     summary: '获取签名发货链接，适合直接跳转平台 Web 发货页',
     scope: 'orders:read + fulfillment:read',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -286,6 +291,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'delivery-order',
     method: 'GET',
     path: '/api/client/v1/orders/{order_no}/delivery',
+    title: '查询发货数据',
     summary: '查询发货页结构化数据，适合商户自建发货界面',
     scope: 'orders:read + fulfillment:read',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -316,6 +322,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'delivery-bind',
     method: 'POST',
     path: '/api/client/v1/orders/{order_no}/delivery/bind',
+    title: '发起绑定',
     summary: '发起绑定，返回绑定跳转链接与二维码地址',
     scope: 'orders:write',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -340,6 +347,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'delivery-submit',
     method: 'POST',
     path: '/api/client/v1/orders/{order_no}/delivery/submit',
+    title: '提交发货',
     summary: '提交发货到上游并进入履约中状态',
     scope: 'orders:write',
     pathParams: [{ name: 'order_no', type: 'string', required: true, desc: '平台订单号', example: 'FO20260730000123' }],
@@ -369,6 +377,7 @@ export const endpoints: EndpointSpec[] = [
     key: 'get-wallet',
     method: 'GET',
     path: '/api/client/v1/wallet',
+    title: '余额查询',
     summary: '查询商户钱包余额',
     scope: 'wallet:read',
     responseExample: `{