{"id":86203,"date":"2026-07-28T09:08:20","date_gmt":"2026-07-28T01:08:20","guid":{"rendered":"https:\/\/www.wsisp.com\/helps\/86203.html"},"modified":"2026-07-28T09:08:20","modified_gmt":"2026-07-28T01:08:20","slug":"%e5%b0%8f%e7%99%bdpython%e5%85%a5%e9%97%a8-50-openapi-%e4%b8%8e%e6%8e%a5%e5%8f%a3%e5%a5%91%e7%ba%a6","status":"publish","type":"post","link":"https:\/\/www.wsisp.com\/helps\/86203.html","title":{"rendered":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6"},"content":{"rendered":"

\u5c0f\u767dpython\u5165\u95e8 – 50. OpenAPI\u4e0e\u63a5\u53e3\u5951\u7ea6<\/h3>\n

1. \u672c\u8bfe\u5b9a\u4f4d：\u662f\u4ec0\u4e48\u3001\u4e3a\u4f55\u91cd\u8981<\/h4>\n

\u524d\u51e0\u8bfe\u4e66\u7b7e API \u5df2\u80fd\u8dd1\u8def\u7531\u3001\u6a21\u578b\u3001\u9274\u6743\u4e0e\u540e\u53f0\u4efb\u52a1\u3002\u4e00\u5230\u8054\u8c03，\u524d\u7aef\u4ecd\u5e38\u95ee：\u5206\u9875\u662f items \u8fd8\u662f data？404 \u957f\u4ec0\u4e48\u6837？\u6539\u5b57\u6bb5\u8981\u4e0d\u8981\u901a\u77e5？\u53ea\u4e22\u4ed3\u5e93\u94fe\u63a5\u4f1a\u53cd\u590d\u8bd5\u9519\u3002<\/p>\n

\u672c\u8282\u628a\u300c\u80fd\u751f\u6210\u6587\u6863\u300d\u5347\u7ea7\u4e3a\u300c\u80fd\u534f\u4f5c\u7684\u5951\u7ea6\u300d：OpenAPI\u3001\/docs\u3001tags\u3001Field \u63cf\u8ff0\u3001\u5206\u9875\u4e0e\u9519\u8bef\u5f62\u72b6\u3001\/api\/v1 \u7248\u672c\u3001\u5bfc\u51fa openapi.json\u3002\u5b66\u5b8c\u5e94\u80fd\u628a Bookmark API \u5199\u6210\u4eba\u4e0e\u5de5\u5177\u90fd\u80fd\u6d88\u8d39\u7684\u7ea6\u5b9a\u3002<\/p>\n

FastAPI \u81ea\u52a8\u751f\u6210 OpenAPI（\/docs\u3001\/redoc\u3001\/openapi.json）\u3002\u300c\u80fd\u751f\u6210\u300d\u2260\u300c\u80fd\u8054\u8c03\u300d\u3002<\/p>\n\n\u6982\u5ff5\u4e00\u53e5\u8bdd<\/tr>\n\n\n\n\n\n\n
OpenAPI<\/td>\nHTTP API \u7684\u673a\u5668\u53ef\u8bfb\u89c4\u8303<\/td>\n<\/tr>\n
\u63a5\u53e3\u5951\u7ea6<\/td>\n\u53cc\u65b9\u540c\u610f\u7684\u8def\u5f84\u3001\u5b57\u6bb5\u3001\u9519\u8bef\u3001\u9274\u6743<\/td>\n<\/tr>\n
Swagger UI<\/td>\n\u6d4f\u89c8\u5668\u4ea4\u4e92\u6587\u6863 \/docs<\/td>\n<\/tr>\n
\u7248\u672c\u5316<\/td>\n\u7834\u574f\u6027\u53d8\u66f4\u5982\u4f55\u5e76\u5b58\u4e0e\u8fc1\u79fb<\/td>\n<\/tr>\n
\u5951\u7ea6\u5bfc\u51fa<\/td>\nopenapi.json \u4ea4\u7ed9\u5de5\u5177\/SDK<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u4e3a\u4f55\u91cd\u8981： API \u662f\u56e2\u961f\u8fb9\u754c\u4ea7\u54c1；\u5951\u7ea6\u4e0d\u6e05，\u8054\u8c03\u6210\u672c\u6307\u6570\u4e0a\u5347\u3002<\/p>\n\n\u5df2\u5b66\u672c\u8bfe<\/tr>\n\n\n\n\n\n
\u6ce8\u89e3\u300c\u987a\u4fbf\u300d\u51fa\u6587\u6863<\/td>\n\u4e3b\u52a8\u5199\u5230\u53ef\u534f\u4f5c<\/td>\n<\/tr>\n
\u4f1a\u5199\u8def\u7531<\/td>\n\u7ea6\u5b9a\u5206\u9875\/\u9519\u8bef\/\u7248\u672c<\/td>\n<\/tr>\n
\/docs \u80fd\u70b9<\/td>\nopenapi.json \u80fd\u5bfc\u51fa<\/td>\n<\/tr>\n
\u5b57\u6bb5\u80fd\u8fc7\u6821\u9a8c<\/td>\n\u5b57\u6bb5\u6709\u8bf4\u660e\u4e0e\u793a\u4f8b<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\u505a\u6cd5\u50cf\u4ec0\u4e48\u5bf9\u5e94<\/tr>\n\n\n\n\n\n\n
\u53e3\u5934\u8bf4\u6709\u5217\u8868<\/td>\n\u83dc\u5355\u65e0\u914d\u6599<\/td>\n\u65e0\u5951\u7ea6<\/td>\n<\/tr>\n
\u6709\u8def\u5f84\u65e0\u63cf\u8ff0<\/td>\n\u83dc\u5355\u53ea\u6709\u83dc\u540d<\/td>\n\u534a\u6210\u54c1<\/td>\n<\/tr>\n
\u7edf\u4e00\u5206\u9875\u9519\u8bef<\/td>\n\u7edf\u4e00\u70b9\u9910\u5355<\/td>\n\u53ef\u590d\u7528<\/td>\n<\/tr>\n
\/api\/v1<\/td>\n\u5927\u6539\u51fa\u7b2c 2 \u7248<\/td>\n\u53ef\u8fc1\u79fb<\/td>\n<\/tr>\n
\u5bfc\u51fa json<\/td>\n\u6807\u51c6\u83dc\u5355\u7ed9\u5e73\u53f0<\/td>\n\u5de5\u5177\u5bfc\u5165<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

2. \u672c\u8d28：\u6587\u6863\u5373\u5951\u7ea6\u7684\u4e00\u90e8\u5206<\/h4>\n

\u5f88\u591a\u4eba\u4ee5\u4e3a OpenAPI \u662f\u5199\u5b8c\u518d\u8865\u7684\u8bf4\u660e\u3002\u5728 FastAPI \u91cc，\u8def\u5f84\u3001\u7c7b\u578b\u3001response_model\u3001\u72b6\u6001\u7801\u3001tags\u3001Field \u90fd\u4f1a\u8fdb\u89c4\u8303\u2014\u2014\u6539\u4ee3\u7801\u5e38\u5373\u6539\u5951\u7ea6\u3002\u672c\u8d28\u662f\u628a HTTP \u8fb9\u754c\u8bf4\u6e05，\u8ba9\u4eba\u3001\u6d4f\u89c8\u5668\u3001\u5de5\u5177\u5171\u7528\u540c\u4e00\u771f\u76f8\u3002<\/p>\n

\u4e0a\u8282\u8bf4\u4e86\u534f\u4f5c\u75db\u3002\u672c\u8282\u5206\u5f00\u300c\u5b9e\u73b0\u7ec6\u8282\u300d\u4e0e\u300c\u5bf9\u5916\u627f\u8bfa\u300d：\u5185\u90e8\u540d\u53ef\u6539，\u5bf9\u5916 JSON \u4e0e\u9519\u8bef\u4f53\u5e94\u7a33\u5b9a\u3002\u5148\u6709\u5951\u7ea6\u611f，\u518d\u5199 tags \u4e0e\u5206\u9875\u6a21\u578b\u3002<\/p>\n

\u672c\u8d28： \u6587\u6863\u662f\u5951\u7ea6\u8f7d\u4f53；\u751f\u6210\u6765\u81ea\u4ee3\u7801，\u63cf\u8ff0\u4e0e\u7ea6\u5b9a\u9760\u4e3b\u52a8\u8865\u9f50\u3002<\/p>\n

\u6ce8\u89e3\/\u6a21\u578b\/tags \u2192 OpenAPI \u2192 \/docs \u7ed9\u4eba | openapi.json \u7ed9\u5de5\u5177 | \u6d4b\u8bd5\u9501\u5f62\u72b6<\/p>\n\n\u5c42\u7ea7\u5185\u5bb9\u6d88\u8d39\u65b9<\/tr>\n\n\n\n\n\n\n
\u8def\u5f84\u65b9\u6cd5<\/td>\nGET \/api\/v1\/bookmarks<\/td>\n\u524d\u7aef\u3001\u6d4b\u8bd5<\/td>\n<\/tr>\n
\u8bf7\u6c42\u6a21\u578b<\/td>\nQuery\/Body \u7ea6\u675f<\/td>\n\u6821\u9a8c+\u6587\u6863<\/td>\n<\/tr>\n
\u54cd\u5e94\u6a21\u578b<\/td>\nPageOut\/BookmarkOut<\/td>\n\u7c7b\u578b\u4e0e\u793a\u4f8b<\/td>\n<\/tr>\n
\u9519\u8bef\u5f62\u72b6<\/td>\n{"detail":"…"}<\/td>\n\u7edf\u4e00\u9519\u8bef\u5904\u7406<\/td>\n<\/tr>\n
\u5143\u4fe1\u606f<\/td>\ntitle\/version\/description<\/td>\n\u5bf9\u63a5\u8bf4\u660e<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\u4fee\u6539\u524d\u4fee\u6539\u540e<\/tr>\n\n\n\n\n\n
\u8fd4\u56de\u4e00\u4e2a list<\/td>\n\u56fa\u5b9a items\/total\/page\/size<\/td>\n<\/tr>\n
\u627e\u4e0d\u5230\u5c31\u629b<\/td>\n404 + detail \u7ea6\u5b9a<\/td>\n<\/tr>\n
\u4ee5\u540e\u518d\u5199\u6587\u6863<\/td>\n\u6539\u63a5\u53e3\u5148\u60f3\u7834\u574f\u6027<\/td>\n<\/tr>\n
\u65e0 description<\/td>\nField \u5e26\u8bf4\u660e\u4e0e examples<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

3. \u7ea6\u675f\u4e0e\u5e38\u89c1\u5751<\/h4>\n

\u5951\u7ea6\u6700\u6015\u4e24\u5f20\u76ae，\u6216\u6bcf\u63a5\u53e3\u4e00\u5957\u5206\u9875\u5b57\u6bb5；\u7834\u574f\u6027\u53d8\u66f4\u4e0d\u5347\u7248\u672c\u4f1a\u8ba9\u524d\u7aef\u65e0\u58f0\u5168\u7ea2；examples \u5199\u771f\u5b9e\u5bc6\u94a5\u5219\u6587\u6863\u4e00\u5bfc\u51fa\u5373\u6cc4\u5bc6\u3002<\/p>\n

\u7ea6\u675f\u4e0e\u5751\u8868\u9489\u7ea2\u7ebf\u540e\u518d\u5199 Field\u3002\u7efc\u5408\u5b9e\u8df5\u6309\u7edf\u4e00\u7ea6\u5b9a\u5b9e\u73b0 PageOut \u4e0e 404\u3002<\/p>\n

\u7ea6\u675f： \u2460\u7834\u574f\u6027\u53d8\u66f4\u5347\u7248\u672c\u6216\u517c\u5bb9\u671f \u2461\u5206\u9875\/\u65f6\u95f4\/\u9519\u8bef\u5168\u9879\u76ee\u7edf\u4e00 \u2462\u9274\u6743\u5728\u6587\u6863\u53ef\u89c1 \u2463\u793a\u4f8b\u7528\u5047\u6570\u636e \u2464\u4ee5\u8fd0\u884c\u4e2d openapi.json \u4e3a\u51c6 \u2465\u4e1a\u52a1\u8def\u5f84\u7528 \/api\/v1\u3002<\/p>\n\n\u5751\u73b0\u8c61\u6b63\u786e\u76f4\u89c9<\/tr>\n\n\n\n\n\n\n\n
\u6587\u6863\u5b9e\u73b0\u4e24\u5f20\u76ae<\/td>\n\u6309\u6587\u6863\u8054\u8c03\u5931\u8d25<\/td>\n\u4ee5\u751f\u6210\u89c4\u8303\u4e3a\u51c6\u5e76\u8865\u63cf\u8ff0<\/td>\n<\/tr>\n
\u5206\u9875\u5b57\u6bb5\u5404\u5f02<\/td>\n\u7ec4\u4ef6\u96be\u590d\u7528<\/td>\n\u7edf\u4e00\u56db\u5b57\u6bb5<\/td>\n<\/tr>\n
\u65e0\u7248\u672c\u524d\u7f00<\/td>\n\u7834\u574f\u65e0\u5904\u53ef\u9003<\/td>\n\/api\/v1<\/td>\n<\/tr>\n
\u793a\u4f8b\u542b\u5bc6\u94a5<\/td>\n\u6cc4\u5bc6<\/td>\n\u5047\u6570\u636e<\/td>\n<\/tr>\n
\u53ea\u5199 200<\/td>\n\u9519\u8bef\u5206\u652f\u778e\u731c<\/td>\nresponses+detail<\/td>\n<\/tr>\n
\u66b4\u9732\u5185\u90e8\u5b57\u6bb5<\/td>\n\u91cd\u6784\u5373\u7834\u574f<\/td>\n\u7a33\u5b9a response_model<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\u517c\u5bb9\u7834\u574f\u6027<\/tr>\n\n\n\n\n
\u65b0\u589e\u53ef\u9009\u5b57\u6bb5\/\u63a5\u53e3<\/td>\n\u5220\u6539\u5b57\u6bb5\u540d\u6216\u7c7b\u578b<\/td>\n<\/tr>\n
\u653e\u5bbd\u6821\u9a8c<\/td>\n\u6536\u7d27\u81f4\u65e7\u5ba2\u6237\u7aef\u5931\u8d25<\/td>\n<\/tr>\n
\u8865\u5145\u9519\u8bef\u8bf4\u660e<\/td>\n\u6539\u9274\u6743\u65e0\u517c\u5bb9<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

4. \u7ea6\u5b9a\u8868：\u5206\u9875\u3001\u9519\u8bef\u3001\u9274\u6743\u3001\u7248\u672c<\/h4>\n

\u5951\u7ea6\u5b9c\u5c11\u800c\u786c\u3002\u4e66\u7b7e API \u5165\u95e8：\u5206\u9875\u56db\u5b57\u6bb5\u3001\u9519\u8bef detail\u3001ISO8601\u3001Bearer\u3001URL \u7248\u672c\u3002\u53ef\u76f4\u63a5\u8d34\u8fdb\u5bf9\u63a5\u8bf4\u660e\u3002<\/p>\n\n\u4e3b\u9898\u5165\u95e8\u7ea6\u5b9a<\/tr>\n\n\n\n\n\n\n\n
\u5206\u9875<\/td>\nitems+total+page+size<\/td>\n<\/tr>\n
\u65f6\u95f4<\/td>\nISO8601，\u4f18\u5148 UTC<\/td>\n<\/tr>\n
\u9519\u8bef<\/td>\n{"detail":"…"}（422 \u4e3a\u5217\u8868）<\/td>\n<\/tr>\n
\u9274\u6743<\/td>\nAuthorization: Bearer <token><\/td>\n<\/tr>\n
\u7248\u672c<\/td>\n\/api\/v1 \u524d\u7f00<\/td>\n<\/tr>\n
\u8fc7\u6ee4<\/td>\nQuery q \u7b49\u53ef\u9009<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

{<\/span>"items"<\/span>:<\/span>[<\/span>{<\/span>"id"<\/span>:<\/span>1<\/span>,<\/span>"title"<\/span>:<\/span>"FastAPI \u6587\u6863"<\/span>,<\/span>"url"<\/span>:<\/span>"https:\/\/fastapi.tiangolo.com"<\/span>}<\/span>]<\/span>,<\/span>"total"<\/span>:<\/span>1<\/span>,<\/span>"page"<\/span>:<\/span>1<\/span>,<\/span>"size"<\/span>:<\/span>10<\/span>}<\/span><\/p>\n\n\u573a\u666f\u7801body<\/tr>\n\n\n\n\n\n
\u672a\u767b\u5f55<\/td>\n401<\/td>\n{"detail":"Not authenticated"}<\/td>\n<\/tr>\n
\u6821\u9a8c\u5931\u8d25<\/td>\n422<\/td>\n{"detail":[…]}<\/td>\n<\/tr>\n
\u4e0d\u5b58\u5728<\/td>\n404<\/td>\n{"detail":"bookmark not found"}<\/td>\n<\/tr>\n
\u51b2\u7a81<\/td>\n409<\/td>\n{"detail":"…"}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\u589e\u5f3a\u624b\u6bb5\u4f5c\u7528<\/tr>\n\n\n\n\n\n\n\n
tags \/ openapi_tags<\/td>\n\u5206\u7ec4<\/td>\n<\/tr>\n
summary \/ docstring<\/td>\n\u4eba\u8bdd\u6807\u9898<\/td>\n<\/tr>\n
Field(description\/examples)<\/td>\n\u5b57\u6bb5\u8bf4\u660e<\/td>\n<\/tr>\n
responses={404:\u2026}<\/td>\n\u9519\u8bef\u8bf4\u660e<\/td>\n<\/tr>\n
version\/description<\/td>\n\u5143\u4fe1\u606f<\/td>\n<\/tr>\n
\u5bfc\u51fa openapi.json<\/td>\n\u5de5\u5177\u5bfc\u5165<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

5. tags \u4e0e\u5e94\u7528\u5143\u4fe1\u606f<\/h4>\n

\u63a5\u53e3\u4e00\u591a \/docs \u53d8\u6210\u957f\u5217\u8868\u3002tags \u5206\u7ec4；openapi_tags \u5199\u7ec4\u8bf4\u660e；title\/version\/description \u505a\u5bf9\u63a5\u62ac\u5934\u3002\u4e0d\u6539\u4e1a\u52a1，\u5374\u663e\u8457\u63d0\u5347\u53ef\u8bfb\u6027\u3002<\/p>\n\n\u9879\u4f5c\u7528<\/tr>\n\n\n\n\n\n\n\n
title<\/td>\n\u5982 Bookmark API<\/td>\n<\/tr>\n
version<\/td>\n\u5982 1.0.0<\/td>\n<\/tr>\n
description<\/td>\nMarkdown \u5bf9\u63a5\u8bf4\u660e<\/td>\n<\/tr>\n
openapi_tags<\/td>\n\u7ec4 name+description<\/td>\n<\/tr>\n
\u8def\u7531 tags<\/td>\n\u63a5\u53e3\u5f52\u7ec4<\/td>\n<\/tr>\n
summary<\/td>\n\u5217\u8868\u77ed\u6807\u9898<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u5c0f\u6b65：<\/p>\n

from<\/span> fastapi import<\/span> FastAPI
\napp =<\/span> FastAPI(<\/span>
\n title=<\/span>"Bookmark API"<\/span>,<\/span> version=<\/span>"1.0.0"<\/span>,<\/span>
\n description=<\/span>"\u4e66\u7b7e\u670d\u52a1\u5165\u95e8\u5951\u7ea6"<\/span>,<\/span>
\n openapi_tags=<\/span>[<\/span>
\n {<\/span>"name"<\/span>:<\/span> "meta"<\/span>,<\/span> "description"<\/span>:<\/span> "\u5065\u5eb7\u68c0\u67e5"<\/span>}<\/span>,<\/span>
\n {<\/span>"name"<\/span>:<\/span> "bookmarks"<\/span>,<\/span> "description"<\/span>:<\/span> "\u4e66\u7b7e\u8d44\u6e90"<\/span>}<\/span>,<\/span>
\n ]<\/span>,<\/span>
\n)<\/span>
\n@app.<\/span>get<\/span>(<\/span>"\/health"<\/span>,<\/span> tags=<\/span>[<\/span>"meta"<\/span>]<\/span>,<\/span> summary=<\/span>"\u5065\u5eb7\u68c0\u67e5"<\/span>)<\/span>
\ndef<\/span> health<\/span>(<\/span>)<\/span>:<\/span>
\n return<\/span> {<\/span>"status"<\/span>:<\/span> "ok"<\/span>}<\/span><\/p>\n

\u9884\u671f： \/docs \u6709 meta \u7ec4\u4e0e\u300c\u5065\u5eb7\u68c0\u67e5\u300d\u6807\u9898\u3002<\/p>\n\n\u4fee\u6539\u524d\u4fee\u6539\u540e<\/tr>\n\n\n\n\n
\u5168\u5806\u9ed8\u8ba4\u7ec4<\/td>\nmeta\/bookmarks \u5206\u7ec4<\/td>\n<\/tr>\n
\u65e0\u7248\u672c<\/td>\nversion \u53ef\u89c1<\/td>\n<\/tr>\n
\u4ec5\u8def\u5f84\u4e32<\/td>\nsummary \u4eba\u8bdd<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

6. Field \u63cf\u8ff0\u3001\u793a\u4f8b\u4e0e response_model<\/h4>\n

\u7c7b\u578b\u53ea\u4fdd\u8bc1 int\/str，\u4e0d\u4fdd\u8bc1\u300c\u9875\u7801\u4ece 1\u300d\u3002Field\/Query \u7684 description\u3001examples \u8fdb OpenAPI；response_model \u56fa\u5b9a\u6210\u529f\u5f62\u72b6\u3002<\/p>\n\n\u5199\u6cd5\u8fdb\u6587\u6863<\/tr>\n\n\n\n\n\n\n
title: str<\/td>\n\u7c7b\u578b<\/td>\n<\/tr>\n
Field(description=…)<\/td>\n\u63cf\u8ff0<\/td>\n<\/tr>\n
Field(examples=[…])<\/td>\n\u5047\u6570\u636e\u793a\u4f8b<\/td>\n<\/tr>\n
Query(1, ge=1, description=…)<\/td>\n\u9ed8\u8ba4+\u7ea6\u675f+\u63cf\u8ff0<\/td>\n<\/tr>\n
response_model=PageOut<\/td>\n\u6210\u529f schema<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u5c0f\u6b65：<\/p>\n

from<\/span> pydantic import<\/span> BaseModel,<\/span> Field
\nfrom<\/span> fastapi import<\/span> Query<\/p>\n

class<\/span> BookmarkOut<\/span>(<\/span>BaseModel)<\/span>:<\/span>
\n id<\/span>:<\/span> int<\/span> =<\/span> Field(<\/span>description=<\/span>"\u4e66\u7b7e ID"<\/span>,<\/span> examples=<\/span>[<\/span>1<\/span>]<\/span>)<\/span>
\n title:<\/span> str<\/span> =<\/span> Field(<\/span>description=<\/span>"\u6807\u9898"<\/span>,<\/span> examples=<\/span>[<\/span>"FastAPI \u6587\u6863"<\/span>]<\/span>)<\/span>
\n url:<\/span> str<\/span> =<\/span> Field(<\/span>description=<\/span>"\u94fe\u63a5"<\/span>,<\/span> examples=<\/span>[<\/span>"https:\/\/fastapi.tiangolo.com"<\/span>]<\/span>)<\/span><\/p>\n

class<\/span> PageOut<\/span>(<\/span>BaseModel)<\/span>:<\/span>
\n items:<\/span> list<\/span>[<\/span>BookmarkOut]<\/span>
\n total:<\/span> int<\/span> =<\/span> Field(<\/span>description=<\/span>"\u603b\u6761\u6570"<\/span>)<\/span>
\n page:<\/span> int<\/span> =<\/span> Field(<\/span>description=<\/span>"\u9875\u7801\u4ece 1"<\/span>)<\/span>
\n size:<\/span> int<\/span> =<\/span> Field(<\/span>description=<\/span>"\u6bcf\u9875\u6761\u6570"<\/span>)<\/span><\/p>\n

def<\/span> params<\/span>(<\/span>
\n page:<\/span> int<\/span> =<\/span> Query(<\/span>1<\/span>,<\/span> ge=<\/span>1<\/span>,<\/span> description=<\/span>"\u9875\u7801\u4ece 1"<\/span>)<\/span>,<\/span>
\n size:<\/span> int<\/span> =<\/span> Query(<\/span>10<\/span>,<\/span> ge=<\/span>1<\/span>,<\/span> le=<\/span>100<\/span>,<\/span> description=<\/span>"\u6bcf\u9875\u6761\u6570"<\/span>)<\/span>,<\/span>
\n q:<\/span> str<\/span> |<\/span> None<\/span> =<\/span> Query(<\/span>None<\/span>,<\/span> description=<\/span>"\u6807\u9898\u5173\u952e\u5b57"<\/span>)<\/span>,<\/span>
\n)<\/span>:<\/span>
\n return<\/span> page,<\/span> size,<\/span> q<\/p>\n

\u9884\u671f： \/docs \u53c2\u6570\u6709\u4e2d\u6587\u8bf4\u660e；Schemas \u6709 PageOut \u56db\u5b57\u6bb5\u3002<\/p>\n\n\u4fee\u6539\u524d\u4fee\u6539\u540e<\/tr>\n\n\n\n\n
\u731c data\/items<\/td>\n\u56fa\u5b9a items<\/td>\n<\/tr>\n
\u9875\u7801\u53e3\u5934\u7ea6\u5b9a<\/td>\ndescription \u5199\u6b7b<\/td>\n<\/tr>\n
\u591a\u8fd4\u56de\u5185\u90e8\u5b57\u6bb5<\/td>\nresponse_model \u88c1\u526a<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

7. \u9519\u8bef\u5f62\u72b6\u4e0e responses<\/h4>\n

\u6210\u529f\u4f53\u5199\u6e05\u540e，\u9519\u8bef\u4ecd\u662f\u9ed1\u6d1e\u3002422 \u9ed8\u8ba4\u6765\u81ea\u6821\u9a8c；\u4e1a\u52a1\u7528 HTTPException \u7edf\u4e00 detail；responses={404:…} \u8ba9\u6587\u6863\u663e\u793a\u5931\u8d25\u8bf4\u660e\u3002<\/p>\n\n\u6765\u6e90\u7801detail<\/tr>\n\n\n\n\n\n
\u7f3a Token<\/td>\n401<\/td>\n\u5b57\u7b26\u4e32<\/td>\n<\/tr>\n
\u975e\u6cd5 Body\/Query<\/td>\n422<\/td>\n\u5217\u8868<\/td>\n<\/tr>\n
HTTPException<\/td>\n\u81ea\u5b9a<\/td>\n\u901a\u5e38\u5b57\u7b26\u4e32<\/td>\n<\/tr>\n
\u672a\u6355\u83b7<\/td>\n500<\/td>\n\u751f\u4ea7\u9690\u85cf\u7ec6\u8282<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u5c0f\u6b65：<\/p>\n

from<\/span> fastapi import<\/span> FastAPI,<\/span> HTTPException,<\/span> Path
\napp =<\/span> FastAPI(<\/span>)<\/span><\/p>\n

@app.<\/span>get<\/span>(<\/span>"\/api\/v1\/bookmarks\/{bookmark_id}"<\/span>,<\/span> responses=<\/span>{<\/span>404<\/span>:<\/span> {<\/span>"description"<\/span>:<\/span> "\u4e0d\u5b58\u5728"<\/span>}<\/span>}<\/span>)<\/span>
\ndef<\/span> get_bookmark<\/span>(<\/span>bookmark_id:<\/span> int<\/span> =<\/span> Path(<\/span>.<\/span>.<\/span>.<\/span>,<\/span> description=<\/span>"\u4e66\u7b7e ID"<\/span>)<\/span>)<\/span>:<\/span>
\n if<\/span> bookmark_id !=<\/span> 1<\/span>:<\/span>
\n raise<\/span> HTTPException(<\/span>status_code=<\/span>404<\/span>,<\/span> detail=<\/span>"bookmark not found"<\/span>)<\/span>
\n return<\/span> {<\/span>"id"<\/span>:<\/span> 1<\/span>,<\/span> "title"<\/span>:<\/span> "demo"<\/span>,<\/span> "url"<\/span>:<\/span> "https:\/\/example.com"<\/span>}<\/span><\/p>\n

\u9884\u671f： 999\u2192404+detail；\/docs \u89c1 404 \u8bf4\u660e\u3002<\/p>\n\n\u4fee\u6539\u524d\u4fee\u6539\u540e<\/tr>\n\n\n\n
{"error":…} \u5404\u5f02<\/td>\n\u7edf\u4e00 detail<\/td>\n<\/tr>\n
\u6587\u6863\u4ec5 200<\/td>\n\u58f0\u660e 404<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n

8. \u7248\u672c\u5316 \/api\/v1 \u4e0e\u5bfc\u51fa openapi.json<\/h4>\n

\u5b57\u6bb5\u7834\u574f\u6027\u53d8\u66f4\u65f6，\u65e0\u7248\u672c\u8def\u5f84\u4f1a\u8ba9\u65e7\u5ba2\u6237\u7aef\u65e0\u58f0\u574f\u6389\u3002\u5165\u95e8\u63a8\u8350 URL \u524d\u7f00：\/api\/v1 \u7a33\u5b9a，\u7834\u574f\u6027\u5f00 \/api\/v2\u3002\u673a\u5668\u4fa7\u5bfc\u51fa \/openapi.json \u7ed9 Apifox\/Postman\/SDK\u3002<\/p>\n\n\u7b56\u7565\u4f18\u52a3\u5efa\u8bae<\/tr>\n\n\n\n\n
URL \/api\/v1<\/td>\n\u76f4\u89c2<\/td>\n\u7565\u957f<\/td>\n\u63a8\u8350<\/td>\n<\/tr>\n
Header \u7248\u672c<\/td>\n\u8def\u5f84\u5e72\u51c0<\/td>\n\u96be\u8c03\u8bd5<\/td>\n\u4e86\u89e3<\/td>\n<\/tr>\n
\u6c38\u4e45\u517c\u5bb9<\/td>\n\u65e0\u8fc1\u79fb<\/td>\n\u5305\u88b1\u91cd<\/td>\n\u96be\u575a\u6301<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\u53d8\u66f4\u5efa\u8bae<\/tr>\n\n\n\n\n
\u65b0\u589e\u53ef\u9009\u5b57\u6bb5<\/td>\nv1 \u5185\u52a0\u5e76\u6587\u6863\u6ce8\u660e<\/td>\n<\/tr>\n
\u5220\u9664\u5fc5\u586b\/\u6539\u7c7b\u578b<\/td>\n\u65b0\u7248\u672c\u6216\u517c\u5bb9\u671f<\/td>\n<\/tr>\n
\u6539\u9274\u6743<\/td>\n\u516c\u544a+\u53cc\u8f68<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\/api\/v1\/bookmarks \/api\/v2\/bookmarks \/health \/openapi.json<\/p>\n\n\u4ea4\u4ed8\u7269\u7ed9\u8c01<\/tr>\n\n\n\n\n
\/docs \/redoc<\/td>\n\u4eba<\/td>\n<\/tr>\n
\/openapi.json<\/td>\n\u5de5\u5177<\/td>\n<\/tr>\n
description\/README<\/td>\n\u524d\u7aef\u5bf9\u63a5<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

curl<\/span> -s<\/span> http:\/\/127.0.0.1:8000\/openapi.json -o<\/span> openapi.json<\/p>\n

\u68c0\u67e5：\u542b paths\u3001PageOut\u3001tags；examples \u65e0\u771f\u5b9e\u5bc6\u94a5\u3002<\/p>\n

\n

9. \u7efc\u5408\u5b9e\u8df5：\u53ef\u534f\u4f5c\u7684 Bookmark API \u5951\u7ea6<\/h4>\n

\u5408\u6210\u6700\u5c0f\u53ef\u8fd0\u884c\u670d\u52a1：\u5065\u5eb7\u68c0\u67e5\u3001\u5206\u9875\u5217\u8868\u3001\u8be6\u60c5 404\u3001\u7edf\u4e00 PageOut\u3001\u8def\u5f84\u5728 \/api\/v1\u3001description \u5199\u5bf9\u63a5\u7ea6\u5b9a\u3002Windows \u82e5 cat <<'EOF' \u4e0d\u53ef\u7528，\u8bf7\u7528 Cygwin \/ Git Bash \/ WSL，\u6216\u624b\u52a8\u5efa main.py\u3002<\/p>\n

mkdir<\/span> -p<\/span> ~\/python-lab\/src\/day50 &&<\/span> cd<\/span> ~\/python-lab\/src\/day50
\npip install<\/span> fastapi "uvicorn[standard]"<\/span><\/p>\n

cat<\/span> ><\/span> main.py <<<\/span> 'EOF'
\nfrom fastapi import FastAPI, HTTPException, Path, Query
\nfrom pydantic import BaseModel, Field<\/p>\n

description = """
\n## Bookmark API \u5bf9\u63a5\u8bf4\u660e（Day50）
\n1. \u672c\u6f14\u793a\u65e0\u771f\u5b9e\u767b\u5f55\u3002
\n2. \u5206\u9875：`items` \/ `total` \/ `page` \/ `size`\u3002
\n3. \u9519\u8bef：`{"detail": "…"}`（422 \u4e3a\u5217\u8868）\u3002
\n4. \u4e1a\u52a1\u8def\u5f84：`\/api\/v1`\u3002
\n5. \u5bfc\u51fa：`\/openapi.json`\u3002
\n"""<\/p>\n

app = FastAPI(
\n title="Bookmark API", description=description, version="1.0.0",
\n openapi_tags=[
\n {"name": "meta", "description": "\u5065\u5eb7\u68c0\u67e5\u4e0e\u5143\u4fe1\u606f"},
\n {"name": "bookmarks", "description": "\u4e66\u7b7e\u8d44\u6e90"},
\n ],
\n)<\/p>\n

class BookmarkOut(BaseModel):
\n id: int = Field(description="\u4e66\u7b7e ID", examples=[1])
\n title: str = Field(description="\u6807\u9898", examples=["FastAPI \u6587\u6863"])
\n url: str = Field(description="\u94fe\u63a5", examples=["https:\/\/fastapi.tiangolo.com"])
\n tags: list[str] = Field(default_factory=list, description="\u6807\u7b7e", examples=[["python"]])<\/p>\n

class PageOut(BaseModel):
\n items: list[BookmarkOut]
\n total: int
\n page: int
\n size: int<\/p>\n

_DB = [
\n BookmarkOut(id=1, title="FastAPI \u6587\u6863", url="https:\/\/fastapi.tiangolo.com", tags=["python", "web"]),
\n BookmarkOut(id=2, title="Pydantic", url="https:\/\/docs.pydantic.dev", tags=["python"]),
\n BookmarkOut(id=3, title="OpenAPI \u89c4\u8303", url="https:\/\/swagger.io\/specification\/", tags=["api"]),
\n]<\/p>\n

@app.get("\/health", tags=["meta"], summary="\u5065\u5eb7\u68c0\u67e5")
\ndef health():
\n return {"status": "ok", "version": "1.0.0"}<\/p>\n

@app.get("\/api\/v1\/bookmarks", tags=["bookmarks"], summary="\u5206\u9875\u5217\u51fa\u4e66\u7b7e", response_model=PageOut)
\ndef list_bookmarks(
\n page: int = Query(1, ge=1, description="\u9875\u7801\u4ece 1"),
\n size: int = Query(10, ge=1, le=100, description="\u6bcf\u9875\u6761\u6570"),
\n q: str | None = Query(None, description="\u6807\u9898\u5173\u952e\u5b57"),
\n):
\n rows = _DB
\n if q:
\n rows = [x for x in rows if q.lower() in x.title.lower()]
\n start = (page – 1) * size
\n return PageOut(items=rows[start:start + size], total=len(rows), page=page, size=size)<\/p>\n

@app.get(
\n "\/api\/v1\/bookmarks\/{bookmark_id}", tags=["bookmarks"], summary="\u4e66\u7b7e\u8be6\u60c5",
\n response_model=BookmarkOut, responses={404: {"description": "\u4e0d\u5b58\u5728"}},
\n)
\ndef get_bookmark(bookmark_id: int = Path(…, ge=1, description="\u4e66\u7b7e ID")):
\n for item in _DB:
\n if item.id == bookmark_id:
\n return item
\n raise HTTPException(status_code=404, detail="bookmark not found")
\nEOF<\/span><\/p>\n

uvicorn main:app –reload<\/span> –port<\/span> 8000<\/span><\/p>\n

\u81ea\u6d4b：<\/p>\n

curl<\/span> -s<\/span> http:\/\/127.0.0.1:8000\/openapi.json -o<\/span> openapi.json
\ncurl<\/span> -s<\/span> "http:\/\/127.0.0.1:8000\/api\/v1\/bookmarks?page=1&size=2"<\/span>
\ncurl<\/span> -s<\/span> "http:\/\/127.0.0.1:8000\/api\/v1\/bookmarks?q=OpenAPI"<\/span>
\ncurl<\/span> -s<\/span> http:\/\/127.0.0.1:8000\/api\/v1\/bookmarks\/1
\ncurl<\/span> -s<\/span> http:\/\/127.0.0.1:8000\/api\/v1\/bookmarks\/999
\ncurl<\/span> -s<\/span> http:\/\/127.0.0.1:8000\/health<\/p>\n\n\u8bf7\u6c42\u9884\u671f<\/tr>\n\n\n\n\n\n\n\n
size=2<\/td>\nitems \u957f 2，total=3<\/td>\n<\/tr>\n
q=OpenAPI<\/td>\n\u547d\u4e2d\u76f8\u5173\u4e66\u7b7e<\/td>\n<\/tr>\n
id=1<\/td>\n\u5b8c\u6574 BookmarkOut<\/td>\n<\/tr>\n
id=999<\/td>\n404 + detail<\/td>\n<\/tr>\n
\/docs<\/td>\n\u5206\u7ec4\u4e0e\u5b57\u6bb5\u8bf4\u660e<\/td>\n<\/tr>\n
openapi.json<\/td>\n\u542b paths \u4e0e PageOut<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u6e05\u5355： title\/version\u3001description \u7ea6\u5b9a\u3001tags\u3001Query \u63cf\u8ff0\u3001404\u3001Schema \u9f50\u5168\u3002<\/p>\n

\n

10. \u80fd\u529b\u603b\u8868\u4e0e\u81ea\u6211\u68c0\u67e5<\/h4>\n

\u8dd1\u901a\u540e\u5bf9\u7167：\u7ea6\u5b9a\u662f\u5426\u7edf\u4e00\u3001\u6587\u6863\u662f\u5426\u589e\u5f3a\u3001json \u80fd\u5426\u5bfc\u51fa\u3002\u67e5\u300c\u53ef\u534f\u4f5c\u300d\u800c\u975e\u4ec5\u300c200\u300d\u3002<\/p>\n\n\u7528\u9014\u505a\u6cd5<\/tr>\n\n\n\n\n\n\n
\u7ed9\u4eba<\/td>\n\/docs \/redoc<\/td>\n<\/tr>\n
\u7ed9\u5de5\u5177<\/td>\n\u5bfc\u51fa openapi.json<\/td>\n<\/tr>\n
\u7ed9\u524d\u7aef<\/td>\n\u5bf9\u63a5\u8bf4\u660e+\u7a33\u5b9a\u5b57\u6bb5<\/td>\n<\/tr>\n
\u7ed9\u6f14\u8fdb<\/td>\n\/api\/v1 \u7248\u672c<\/td>\n<\/tr>\n
\u7ed9\u6d4b\u8bd5<\/td>\n\u4e0b\u8282\u65ad\u8a00\u9501\u5951\u7ea6<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n
  • \u8bf4\u6e05 OpenAPI \u4e0e\u5951\u7ea6<\/li>\n
  • \u5206\u9875\u56db\u5b57\u6bb5\u7edf\u4e00<\/li>\n
  • \u9519\u8bef\u4ee5 detail \u4e3a\u4e3b<\/li>\n
  • tags + Field \u5df2\u5199<\/li>\n
  • \u8def\u5f84\u5728 \/api\/v1<\/li>\n
  • \u4f1a\u5bfc\u51fa openapi.json<\/li>\n
  • \u77e5\u7834\u574f\u6027\u8981\u7248\u672c<\/li>\n
  • \u793a\u4f8b\u65e0\u5bc6\u94a5<\/li>\n<\/ul>\n
    \n

    \u603b\u7ed3<\/h3>\n

    \u4ece\u300c\u751f\u6210\u80fd\u70b9\u300d\u5230\u300c\u7ea6\u5b9a\u53ef\u534f\u4f5c\u300d，\u8981\u628a\u5206\u9875\u3001\u9519\u8bef\u3001\u7248\u672c\u4e0e\u5b57\u6bb5\u8bf4\u660e\u5f53\u4ea7\u54c1\u3002OpenAPI \u662f\u673a\u5668\u5951\u7ea6；\/docs \u7ed9\u4eba；openapi.json \u7ed9\u5de5\u5177\u3002Bookmark API \u7edf\u4e00\u5f62\u72b6\u5e76\u6302 \/api\/v1，\u8054\u8c03\u6210\u672c\u4f1a\u4e0b\u964d\u3002\u4e0b\u8282\u7528\u6d4b\u8bd5\u9501\u4f4f\u5f62\u72b6\u3002<\/p>\n

      \n
    • OpenAPI \u63cf\u8ff0 API；\u5951\u7ea6\u662f\u53cc\u65b9\u540c\u610f\u7684\u5f62\u72b6\u4e0e\u884c\u4e3a\u3002<\/li>\n
    • \u4ee3\u7801\u751f\u6210\u89c4\u8303；tags\/Field\/response_model \u51b3\u5b9a\u53ef\u8bfb\u6027\u3002<\/li>\n
    • \u5206\u9875\u7edf\u4e00 items\/total\/page\/size；\u9519\u8bef\u4f18\u5148 detail\u3002<\/li>\n
    • \u7834\u574f\u6027\u53d8\u66f4\u7528\u7248\u672c\u6216\u517c\u5bb9\u671f\u3002<\/li>\n
    • \u5bfc\u51fa openapi.json；\u793a\u4f8b\u7528\u5047\u6570\u636e；\u4ee5\u8fd0\u884c\u4e2d\u89c4\u8303\u4e3a\u51c6\u3002<\/li>\n<\/ul>\n
      \n

      \u5c0f\u7ec3\u7b14<\/h3>\n

      \u5951\u7ea6\u5df2\u4ece\u7ea6\u5b9a\u8868\u843d\u5230\u53ef\u8fd0\u884c\u670d\u52a1\u3002\u5148\u72ec\u7acb\u4f5c\u7b54；\u5efa\u8bae\u5bf9\u7167 \/docs \u4e0e openapi.json\u3002<\/p>\n

      \u9898 1<\/h4>\n

      \/openapi.json \u7ed9\u8c01\u7528？\u4e3e\u4e24\u7c7b\u6d88\u8d39\u8005\u3002<\/p>\n

      \u9898 2<\/h4>\n

      \u4e3a\u4f55\u5206\u9875\u5b57\u6bb5\u8981\u5168\u9879\u76ee\u7edf\u4e00？<\/p>\n

      \u9898 3<\/h4>\n

      \u7834\u574f\u6027\u5220\u9664\u54cd\u5e94\u5b57\u6bb5\u65f6\u5982\u4f55\u7248\u672c\u5316？<\/p>\n

      \u9898 4<\/h4>\n

      \u5224\u65ad：\u6709 \/docs \u5c31\u7b49\u4e8e\u524d\u7aef\u65e0\u9700\u5176\u5b83\u8bf4\u660e\u3002（\u5bf9\/\u9519）<\/p>\n

      \u9898 5<\/h4>\n

      \u5199\u51fa\u5206\u9875\u6210\u529f JSON \u9aa8\u67b6（items\/total\/page\/size）\u3002<\/p>\n

      \u9898 6<\/h4>\n

      Field(description\/examples) \u6bd4\u53ea\u5199 title: str \u591a\u4e86\u4ec0\u4e48？<\/p>\n

      \u9898 7<\/h4>\n

      \u4e3a\u4f55\u4e1a\u52a1\u63a5\u53e3\u5efa\u8bae \/api\/v1？<\/p>\n

      \u9898 8<\/h4>\n

      \u8be6\u60c5\u627e\u4e0d\u5230\u4e66\u7b7e\u65f6\u7684\u72b6\u6001\u7801\u4e0e body？<\/p>\n

      \u9898 9<\/h4>\n

      \u54ea\u9879\u662f\u517c\u5bb9\u53d8\u66f4？A \u5220 url B \u65b0\u589e\u53ef\u9009 tags C id \u6539 string<\/p>\n

      \u9898 10（\u53ef\u9009）<\/h4>\n

      \u5bfc\u51fa openapi.json，\u786e\u8ba4\u542b \/api\/v1\/bookmarks \u4e0e PageOut\u3002<\/p>\n

      \n

      \u5c0f\u7ec3\u7b14\u53c2\u8003\u7b54\u6848<\/h3>\n

      \u5148\u505a\u540e\u770b\u3002<\/p>\n

      \u9898 1<\/h4>\n

      \u5de5\u5177\u5bfc\u5165（Postman\/Apifox）\u3001\u751f\u6210\u5ba2\u6237\u7aef\/SDK\u3001\u5951\u7ea6\u6821\u9a8c\u7b49\u3002<\/p>\n

      \u9898 2<\/h4>\n

      \u524d\u7aef\u7ec4\u4ef6\u4e0e SDK \u53ef\u590d\u7528，\u964d\u8054\u8c03\u6210\u672c\u3002<\/p>\n

      \u9898 3<\/h4>\n

      \u5347\u4e3b\u7248\u672c\u6216 \/api\/v2，\u7ed9\u8fc1\u79fb\/\u517c\u5bb9\u671f\u5e76\u66f4\u65b0\u6587\u6863\u3002<\/p>\n

      \u9898 4<\/h4>\n

      \u9519<\/p>\n

      \u9898 5<\/h4>\n

      {"items":[],"total":0,"page":1,"size":10}<\/p>\n

      \u9898 6<\/h4>\n

      \u4eba\u7c7b\u53ef\u8bfb\u63cf\u8ff0\u4e0e\u793a\u4f8b，\u6587\u6863\u66f4\u6e05\u6670\u3002<\/p>\n

      \u9898 7<\/h4>\n

      \u7834\u574f\u6027\u53ef\u5e76\u5b58\u65b0\u7248\u672c；\u7f51\u5173\u4e0e\u8def\u7531\u597d\u5207\u5206\u3002<\/p>\n

      \u9898 8<\/h4>\n

      404，{"detail":"bookmark not found"}<\/p>\n

      \u9898 9<\/h4>\n

      B<\/p>\n

      \u9898 10<\/h4>\n

      \u6587\u4ef6\u4e2d\u80fd\u641c\u5230\u8def\u5f84\u4e0e PageOut\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"

      \u5c0f\u767dpython\u5165\u95e8 – 50. OpenAPI\u4e0e\u63a5\u53e3\u5951\u7ea6
      \n1. \u672c\u8bfe\u5b9a\u4f4d：\u662f\u4ec0\u4e48\u3001\u4e3a\u4f55\u91cd\u8981\u524d\u51e0\u8bfe\u4e66\u7b7e API \u5df2\u80fd\u8dd1\u8def\u7531\u3001\u6a21\u578b\u3001\u9274\u6743\u4e0e\u540e\u53f0\u4efb\u52a1\u3002\u4e00\u5230\u8054\u8c03，\u524d\u7aef\u4ecd\u5e38\u95ee：\u5206\u9875\u662f items \u8fd8\u662f data？404 \u957f\u4ec0\u4e48\u6837？\u6539\u5b57\u6bb5\u8981\u4e0d\u8981\u901a\u77e5？\u53ea\u4e22\u4ed3\u5e93\u94fe\u63a5\u4f1a\u53cd\u590d\u8bd5\u9519\u3002
      \n\u672c\u8282\u628a\u300c\u80fd\u751f\u6210\u6587\u6863\u300d\u5347\u7ea7\u4e3a\u300c\u80fd\u534f\u4f5c\u7684\u5951\u7ea6\u300d：OpenAPI\u3001\/docs\u3001tags\u3001Field \u63cf\u8ff0\u3001\u5206\u9875\u4e0e\u9519\u8bef\u5f62\u72b6\u3001<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[81,190],"topic":[],"class_list":["post-86203","post","type-post","status-publish","format-standard","hentry","category-server","tag-python","tag-190"],"yoast_head":"\n\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.wsisp.com\/helps\/86203.html\" \/>\n<meta property=\"og:locale\" content=\"zh_CN\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\" \/>\n<meta property=\"og:description\" content=\"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI\u4e0e\u63a5\u53e3\u5951\u7ea6 1. \u672c\u8bfe\u5b9a\u4f4d：\u662f\u4ec0\u4e48\u3001\u4e3a\u4f55\u91cd\u8981\u524d\u51e0\u8bfe\u4e66\u7b7e API \u5df2\u80fd\u8dd1\u8def\u7531\u3001\u6a21\u578b\u3001\u9274\u6743\u4e0e\u540e\u53f0\u4efb\u52a1\u3002\u4e00\u5230\u8054\u8c03，\u524d\u7aef\u4ecd\u5e38\u95ee：\u5206\u9875\u662f items \u8fd8\u662f data？404 \u957f\u4ec0\u4e48\u6837？\u6539\u5b57\u6bb5\u8981\u4e0d\u8981\u901a\u77e5？\u53ea\u4e22\u4ed3\u5e93\u94fe\u63a5\u4f1a\u53cd\u590d\u8bd5\u9519\u3002 \u672c\u8282\u628a\u300c\u80fd\u751f\u6210\u6587\u6863\u300d\u5347\u7ea7\u4e3a\u300c\u80fd\u534f\u4f5c\u7684\u5951\u7ea6\u300d：OpenAPI\u3001\/docs\u3001tags\u3001Field \u63cf\u8ff0\u3001\u5206\u9875\u4e0e\u9519\u8bef\u5f62\u72b6\u3001\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.wsisp.com\/helps\/86203.html\" \/>\n<meta property=\"og:site_name\" content=\"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\" \/>\n<meta property=\"article:published_time\" content=\"2026-07-28T01:08:20+00:00\" \/>\n<meta name=\"author\" content=\"admin\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"\u4f5c\u8005\" \/>\n\t<meta name=\"twitter:data1\" content=\"admin\" \/>\n\t<meta name=\"twitter:label2\" content=\"\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4\" \/>\n\t<meta name=\"twitter:data2\" content=\"5 \u5206\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/86203.html\",\"url\":\"https:\/\/www.wsisp.com\/helps\/86203.html\",\"name\":\"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\",\"isPartOf\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/#website\"},\"datePublished\":\"2026-07-28T01:08:20+00:00\",\"dateModified\":\"2026-07-28T01:08:20+00:00\",\"author\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41\"},\"breadcrumb\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/86203.html#breadcrumb\"},\"inLanguage\":\"zh-Hans\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/www.wsisp.com\/helps\/86203.html\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/86203.html#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"\u9996\u9875\",\"item\":\"https:\/\/www.wsisp.com\/helps\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#website\",\"url\":\"https:\/\/www.wsisp.com\/helps\/\",\"name\":\"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\",\"description\":\"\u9999\u6e2f\u670d\u52a1\u5668_\u9999\u6e2f\u4e91\u670d\u52a1\u5668\u8d44\u8baf_\u670d\u52a1\u5668\u5e2e\u52a9\u6587\u6863_\u670d\u52a1\u5668\u6559\u7a0b\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.wsisp.com\/helps\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"zh-Hans\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41\",\"name\":\"admin\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"zh-Hans\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery\",\"contentUrl\":\"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery\",\"caption\":\"admin\"},\"sameAs\":[\"http:\/\/wp.wsisp.com\"],\"url\":\"https:\/\/www.wsisp.com\/helps\/author\/admin\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.wsisp.com\/helps\/86203.html","og_locale":"zh_CN","og_type":"article","og_title":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","og_description":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI\u4e0e\u63a5\u53e3\u5951\u7ea6 1. \u672c\u8bfe\u5b9a\u4f4d：\u662f\u4ec0\u4e48\u3001\u4e3a\u4f55\u91cd\u8981\u524d\u51e0\u8bfe\u4e66\u7b7e API \u5df2\u80fd\u8dd1\u8def\u7531\u3001\u6a21\u578b\u3001\u9274\u6743\u4e0e\u540e\u53f0\u4efb\u52a1\u3002\u4e00\u5230\u8054\u8c03，\u524d\u7aef\u4ecd\u5e38\u95ee：\u5206\u9875\u662f items \u8fd8\u662f data？404 \u957f\u4ec0\u4e48\u6837？\u6539\u5b57\u6bb5\u8981\u4e0d\u8981\u901a\u77e5？\u53ea\u4e22\u4ed3\u5e93\u94fe\u63a5\u4f1a\u53cd\u590d\u8bd5\u9519\u3002 \u672c\u8282\u628a\u300c\u80fd\u751f\u6210\u6587\u6863\u300d\u5347\u7ea7\u4e3a\u300c\u80fd\u534f\u4f5c\u7684\u5951\u7ea6\u300d：OpenAPI\u3001\/docs\u3001tags\u3001Field \u63cf\u8ff0\u3001\u5206\u9875\u4e0e\u9519\u8bef\u5f62\u72b6\u3001","og_url":"https:\/\/www.wsisp.com\/helps\/86203.html","og_site_name":"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","article_published_time":"2026-07-28T01:08:20+00:00","author":"admin","twitter_card":"summary_large_image","twitter_misc":{"\u4f5c\u8005":"admin","\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4":"5 \u5206"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.wsisp.com\/helps\/86203.html","url":"https:\/\/www.wsisp.com\/helps\/86203.html","name":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","isPartOf":{"@id":"https:\/\/www.wsisp.com\/helps\/#website"},"datePublished":"2026-07-28T01:08:20+00:00","dateModified":"2026-07-28T01:08:20+00:00","author":{"@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41"},"breadcrumb":{"@id":"https:\/\/www.wsisp.com\/helps\/86203.html#breadcrumb"},"inLanguage":"zh-Hans","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.wsisp.com\/helps\/86203.html"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.wsisp.com\/helps\/86203.html#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"\u9996\u9875","item":"https:\/\/www.wsisp.com\/helps"},{"@type":"ListItem","position":2,"name":"\u5c0f\u767dpython\u5165\u95e8 - 50. OpenAPI \u4e0e\u63a5\u53e3\u5951\u7ea6"}]},{"@type":"WebSite","@id":"https:\/\/www.wsisp.com\/helps\/#website","url":"https:\/\/www.wsisp.com\/helps\/","name":"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","description":"\u9999\u6e2f\u670d\u52a1\u5668_\u9999\u6e2f\u4e91\u670d\u52a1\u5668\u8d44\u8baf_\u670d\u52a1\u5668\u5e2e\u52a9\u6587\u6863_\u670d\u52a1\u5668\u6559\u7a0b","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.wsisp.com\/helps\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"zh-Hans"},{"@type":"Person","@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41","name":"admin","image":{"@type":"ImageObject","inLanguage":"zh-Hans","@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/image\/","url":"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery","contentUrl":"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery","caption":"admin"},"sameAs":["http:\/\/wp.wsisp.com"],"url":"https:\/\/www.wsisp.com\/helps\/author\/admin"}]}},"_links":{"self":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts\/86203","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/comments?post=86203"}],"version-history":[{"count":0,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts\/86203\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/media?parent=86203"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/categories?post=86203"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/tags?post=86203"},{"taxonomy":"topic","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/topic?post=86203"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}