https://chihhung.github.io/Blog/tags/openapi/Recent content in OpenAPI on Eric 個人部落格Hugo -- 0.151.0zh-TWMon, 18 May 2026 00:00:00 +0000https://chihhung.github.io/Blog/posts/%E6%95%99%E5%AD%B8/templates/design/api_spec_template/Mon, 18 May 2026 00:00:00 +0000https://chihhung.github.io/Blog/posts/%E6%95%99%E5%AD%B8/templates/design/api_spec_template/<h1 id="api-規格文件範本api-specification-document">API 規格文件範本（API Specification Document）</h1> <blockquote> <p><strong>參照標準</strong>：OpenAPI Specification 3.1（OAS 3.1）/ Linux Foundation 標準<br> <strong>文件用途</strong>：定義 RESTful API 的端點、請求/回應格式、認證機制與錯誤處理規範<br> <strong>適用階段</strong>：系統設計階段（Detail Design Phase）</p></blockquote> <hr> <h2 id="-章節目錄">📋 章節目錄</h2> <ol> <li><a href="#1-%E6%96%87%E4%BB%B6%E8%B3%87%E8%A8%8A">文件資訊</a></li> <li><a href="#2-api-%E6%A6%82%E8%BF%B0">API 概述</a></li> <li><a href="#3-%E8%AA%8D%E8%AD%89%E8%88%87%E6%8E%88%E6%AC%8A">認證與授權</a></li> <li><a href="#4-%E5%85%B1%E7%94%A8%E8%A6%8F%E7%AF%84">共用規範</a></li> <li><a href="#5-%E7%AB%AF%E9%BB%9E%E5%AE%9A%E7%BE%A9">端點定義</a></li> <li><a href="#6-%E8%B3%87%E6%96%99%E6%A8%A1%E5%9E%8Bschemas">資料模型</a></li> <li><a href="#7-%E9%8C%AF%E8%AA%A4%E8%99%95%E7%90%86">錯誤處理</a></li> <li><a href="#8-%E7%89%88%E6%9C%AC%E7%AD%96%E7%95%A5">版本策略</a></li> <li><a href="#9-openapi-%E8%A6%8F%E6%A0%BC%E6%AA%94">OpenAPI 規格檔</a></li> <li><a href="#10-%E9%99%84%E9%8C%84">附錄</a></li> </ol> <hr> <h2 id="1-文件資訊">1. 文件資訊</h2> <h3 id="-範本">📝 範本</h3> <table> <thead> <tr> <th>項目</th> <th>內容</th> </tr> </thead> <tbody> <tr> <td><strong>文件編號</strong></td> <td>API-{專案代碼}-{序號}</td> </tr> <tr> <td><strong>API 名稱</strong></td> <td>{系統名稱} API</td> </tr> <tr> <td><strong>API 版本</strong></td> <td>v{主版本}</td> </tr> <tr> <td><strong>文件版本</strong></td> <td>v{主版本}.{次版本}</td> </tr> <tr> <td><strong>狀態</strong></td> <td>草稿 / 審核中 / 已發布</td> </tr> <tr> <td><strong>建立日期</strong></td> <td>{YYYY-MM-DD}</td> </tr> <tr> <td><strong>最後更新</strong></td> <td>{YYYY-MM-DD}</td> </tr> <tr> <td><strong>負責人</strong></td> <td>{姓名/角色}</td> </tr> <tr> <td><strong>Base URL</strong></td> <td><code>https://{domain}/api/v{version}</code></td> </tr> </tbody> </table> <h3 id="-使用說明">📖 使用說明</h3> <ul> <li>API 版本與文件版本分開管理：API 版本影響端點路徑，文件版本追蹤文件修訂</li> <li>Base URL 需區分環境（DEV/SIT/UAT/PROD）</li> <li>依據 OpenAPI 3.1 info 物件結構設計</li> </ul> <h3 id="-範例">💡 範例</h3> <table> <thead> <tr> <th>項目</th> <th>內容</th> </tr> </thead> <tbody> <tr> <td><strong>文件編號</strong></td> <td>API-HRM-001</td> </tr> <tr> <td><strong>API 名稱</strong></td> <td>HRMS API</td> </tr> <tr> <td><strong>API 版本</strong></td> <td>v1</td> </tr> <tr> <td><strong>Base URL</strong></td> <td><code>https://api.company.com/hrms/v1</code></td> </tr> </tbody> </table> <hr> <h2 id="2-api-概述">2. API 概述</h2> <h3 id="-範本-1">📝 範本</h3> <h4 id="21-api-目的">2.1 API 目的</h4> <p>{描述此 API 提供的服務範圍與主要功能}</p>