fix(docs): warehouse 文档作为外部 API 隔离,不暴露内部文档导航;修正签名算法描述为 MD5
This commit is contained in:
parent
da4208707d
commit
b5b631f20d
@ -535,13 +535,15 @@ function renderMethodCard(item, entryPath, moduleName) {
|
||||
const description = item.description || '';
|
||||
const isQimen = moduleName === 'qimen';
|
||||
const isOpenapi = moduleName === 'openapi';
|
||||
const isWarehouse = moduleName === 'warehouse';
|
||||
const isExternalApi = isOpenapi || isWarehouse;
|
||||
const queryHint = isQimen
|
||||
? 'app_key=xxx&method=...&v=2.0&format=json&sign_method=md5&sign=xxx×tamp=1700000000'
|
||||
: isOpenapi
|
||||
: isExternalApi
|
||||
? `app_key=&method=${methodName}&v=1.0×tamp=1700000000`
|
||||
: `method=${methodName}&v=1.0×tamp=1700000000`;
|
||||
const queryLabel = isOpenapi ? 'Query 参数(自动生成)' : 'Query 参数';
|
||||
const queryReadonlyAttr = isOpenapi ? ' readonly data-auto-generated="true" aria-label="自动生成"' : '';
|
||||
const queryLabel = isExternalApi ? 'Query 参数(自动生成)' : 'Query 参数';
|
||||
const queryReadonlyAttr = isExternalApi ? ' readonly data-auto-generated="true" aria-label="自动生成"' : '';
|
||||
|
||||
return `<section class="method-card" id="${escapeHtml(methodName)}" data-method="${escapeHtml(methodName)}" data-desc="${escapeHtml(description)}" data-module="${escapeHtml(moduleName || '')}" data-endpoint="${escapeHtml(entryPath)}" data-login-required="${item.isNeedLogin ? 'true' : 'false'}">
|
||||
<div class="method-header">
|
||||
@ -614,7 +616,7 @@ function renderMethodCard(item, entryPath, moduleName) {
|
||||
<label>${queryLabel}</label>
|
||||
<input class="req-query" type="text" placeholder="${escapeHtml(queryHint)}"${queryReadonlyAttr} />
|
||||
|
||||
${isOpenapi ? `<label>app_key(仅 openapi 页面本地保存)</label>
|
||||
${isExternalApi ? `<label>app_key(仅外部 API 页面本地保存)</label>
|
||||
<input class="req-app-key" type="text" placeholder="请输入 app_key" autocomplete="off" />
|
||||
<label>self_app_secret(仅本地签名计算,不会发送)</label>
|
||||
<input class="req-self-app-secret" type="password" placeholder="请输入 self_app_secret" autocomplete="off" />` : ''}
|
||||
@ -646,12 +648,14 @@ function renderHtmlPage({
|
||||
entryPath,
|
||||
}) {
|
||||
const isOpenapi = docData.module === 'openapi';
|
||||
const isWarehouse = docData.module === 'warehouse';
|
||||
const isExternalApi = isOpenapi || isWarehouse;
|
||||
const methodsCount = groups.reduce((sum, group) => sum + toArray(group.list).length, 0);
|
||||
const globalHeaders = toArray(docData.headers);
|
||||
const globalHeadersControls = renderGlobalHeadersControls(globalHeaders);
|
||||
const rawUrl = `/api/docs/${encodeURIComponent(docName)}/raw`;
|
||||
const changesUrl = `/api/docs/${encodeURIComponent(docName)}/changes`;
|
||||
const navHtml = isOpenapi ? '' : docs.filter(name => name !== 'openapi').map(name => {
|
||||
const navHtml = isExternalApi ? '' : docs.filter(name => name !== 'openapi' && name !== 'warehouse').map(name => {
|
||||
const activeClass = name === docName ? 'active' : '';
|
||||
return `<a class="tab ${activeClass}" href="/api/docs/${encodeURIComponent(name)}">${escapeHtml(name)}</a>`;
|
||||
}).join('');
|
||||
@ -1076,7 +1080,7 @@ function renderHtmlPage({
|
||||
<a class="tab" href="${escapeHtml(changesUrl)}">查看变更记录</a>
|
||||
<a class="tab" href="${escapeHtml(rawUrl)}">查看 JSON</a>
|
||||
</div>
|
||||
${isOpenapi ? '' : `<div class="global-auth">
|
||||
${isExternalApi ? '' : `<div class="global-auth">
|
||||
<h3>全局 Authorization</h3>
|
||||
<div class="row">
|
||||
<input id="globalAuth" type="text" placeholder="Bearer xxxxx" />
|
||||
@ -1087,7 +1091,7 @@ function renderHtmlPage({
|
||||
${globalHeadersControls}
|
||||
<p class="muted">来自 JSON 的 headers 定义;带 * 的字段为必填,支持下拉 list 选择。</p>
|
||||
</div>`}
|
||||
${isOpenapi ? '' : `<div class="doc-tools">
|
||||
${isExternalApi ? '' : `<div class="doc-tools">
|
||||
<h3>文档资源</h3>
|
||||
<div class="doc-tools-actions">
|
||||
${renderWindowElement('打开变更记录', changesUrl, 'doc-resource-link')}
|
||||
@ -1097,9 +1101,9 @@ function renderHtmlPage({
|
||||
</div>
|
||||
<pre id="docResourcePreview" class="req-result muted">点击上方按钮后,可直接预览当前文档的变更记录或原文 JSON。</pre>
|
||||
</div>`}
|
||||
${isOpenapi ? `<div class="openapi-guide">
|
||||
${isExternalApi ? `<div class="openapi-guide">
|
||||
<h3>请求方式</h3>
|
||||
<pre class="guide-code">POST /openapi?method={方法名}&v=1.0×tamp={时间戳}&app_key={app_key}&sign={签名}
|
||||
<pre class="guide-code">POST ${isOpenapi ? '/openapi' : '/warehouse'}?method={方法名}&v=1.0×tamp={时间戳}&app_key={app_key}&sign={签名}
|
||||
Content-Type: application/json
|
||||
|
||||
{请求体 JSON}</pre>
|
||||
@ -1138,10 +1142,10 @@ Content-Type: application/json
|
||||
<li>时间戳 <strong>timestamp</strong> 时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),超时返回 400</li>
|
||||
<li>签名结果为 32 位小写十六进制字符串</li>
|
||||
</ul>
|
||||
<p style="margin-top:12px;font-size:13px;">
|
||||
${isOpenapi ? `<p style="margin-top:12px;font-size:13px;">
|
||||
<a href="/docs/api/openapi/callback-test" style="color:#1565c0;">→ 回调测试工具</a>
|
||||
<span class="muted">(模拟接收回调通知,验证回调链路)</span>
|
||||
</p>
|
||||
</p>` : ''}
|
||||
</div>` : ''}
|
||||
</section>
|
||||
|
||||
@ -1167,9 +1171,10 @@ Content-Type: application/json
|
||||
(function() {
|
||||
var DOC_NAME = ${JSON.stringify(docName)};
|
||||
var IS_OPENAPI_DOC = DOC_NAME === 'openapi';
|
||||
var IS_EXTERNAL_API_DOC = DOC_NAME === 'openapi' || DOC_NAME === 'warehouse';
|
||||
var AUTH_KEY = 'wms_docs_global_auth';
|
||||
var HEADER_STORE_KEY = 'wms_docs_global_headers_' + ${JSON.stringify(docName)};
|
||||
var OPENAPI_APP_KEY_STORE_KEY = 'wms_docs_openapi_app_key';
|
||||
var OPENAPI_APP_KEY_STORE_KEY = 'wms_docs_' + DOC_NAME + '_app_key';
|
||||
var authInput = document.getElementById('globalAuth');
|
||||
var clearBtn = document.getElementById('clearAuthBtn');
|
||||
var searchInput = document.getElementById('methodSearch');
|
||||
@ -1547,7 +1552,7 @@ Content-Type: application/json
|
||||
return 'app_key=&method=' + encodeURIComponent(methodName)
|
||||
+ '&v=2.0&format=json&sign_method=md5&sign=×tamp=' + nowTimestamp();
|
||||
}
|
||||
if (moduleName === 'openapi') {
|
||||
if (moduleName === 'openapi' || moduleName === 'warehouse') {
|
||||
return buildOpenapiQuery(card, '');
|
||||
}
|
||||
return 'method=' + encodeURIComponent(methodName) + '&v=1.0×tamp=' + nowTimestamp();
|
||||
@ -1573,7 +1578,7 @@ Content-Type: application/json
|
||||
var bodyInput = card.querySelector('.req-body');
|
||||
var moduleName = card.getAttribute('data-module') || '';
|
||||
if (queryInput) {
|
||||
if (moduleName === 'openapi') {
|
||||
if (moduleName === 'openapi' || moduleName === 'warehouse') {
|
||||
var appKeyInput = card.querySelector('.req-app-key');
|
||||
var openapiAppKey = (appKeyInput && appKeyInput.value.trim()) || '';
|
||||
queryInput.value = buildOpenapiQuery(card, openapiAppKey);
|
||||
@ -1593,11 +1598,11 @@ Content-Type: application/json
|
||||
* @return {void}
|
||||
*/
|
||||
function refreshOpenapiQueryDisplays(appKey) {
|
||||
if (!IS_OPENAPI_DOC) {
|
||||
if (!IS_EXTERNAL_API_DOC) {
|
||||
return;
|
||||
}
|
||||
|
||||
var cards = document.querySelectorAll('.method-card[data-module="openapi"]');
|
||||
var cards = document.querySelectorAll('.method-card[data-module="openapi"], .method-card[data-module="warehouse"]');
|
||||
cards.forEach(function(card) {
|
||||
var queryInput = card.querySelector('.req-query');
|
||||
if (!queryInput) {
|
||||
@ -1613,7 +1618,7 @@ Content-Type: application/json
|
||||
* @return {void}
|
||||
*/
|
||||
function initOpenapiAppKeyInputs() {
|
||||
if (!IS_OPENAPI_DOC) {
|
||||
if (!IS_EXTERNAL_API_DOC) {
|
||||
return;
|
||||
}
|
||||
|
||||
@ -1856,7 +1861,7 @@ Content-Type: application/json
|
||||
return;
|
||||
}
|
||||
|
||||
if (moduleName === 'openapi') {
|
||||
if (moduleName === 'openapi' || moduleName === 'warehouse') {
|
||||
var appKeyInput = card.querySelector('.req-app-key');
|
||||
var openapiAppKey = (appKeyInput && appKeyInput.value.trim()) || '';
|
||||
query = buildOpenapiQuery(card, openapiAppKey);
|
||||
@ -2040,6 +2045,14 @@ class DocsController extends Controller {
|
||||
await this.renderDoc('openapi');
|
||||
}
|
||||
|
||||
/**
|
||||
* 渲染仓库开放 API 文档独立页面。
|
||||
* @return {Promise<void>} 无返回值。
|
||||
*/
|
||||
async warehouse() {
|
||||
await this.renderDoc('warehouse');
|
||||
}
|
||||
|
||||
async detail() {
|
||||
const { ctx } = this;
|
||||
const docName = ctx.params.docName;
|
||||
|
||||
@ -33,6 +33,9 @@ module.exports = app => {
|
||||
// OpenAPI 文档 — 所有环境均可访问,必须在通配路由之前注册
|
||||
router.get('/docs/api/openapi', controller.docs.openapi);
|
||||
|
||||
// Warehouse 开放 API 文档 — 所有环境均可访问
|
||||
router.get('/docs/api/warehouse', controller.docs.warehouse);
|
||||
|
||||
// OpenAPI 回调测试 — 所有环境均可访问的独立调试页面
|
||||
router.get('/docs/api/openapi/callback-test', controller.openapiCallback.testPage);
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"module": "warehouse",
|
||||
"description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 HMAC-SHA256 签名鉴权(interface_type_id=3)",
|
||||
"description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)",
|
||||
"version": "1.0.0",
|
||||
"updatedAt": "2026-08-01",
|
||||
"http": {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user