{"id":56360,"date":"2023-10-13T23:33:56","date_gmt":"2023-10-13T15:33:56","guid":{"rendered":"https:\/\/docs.pingcode.com\/?p=56360"},"modified":"2023-10-13T23:34:01","modified_gmt":"2023-10-13T15:34:01","slug":"%e5%a6%82%e4%bd%95%e4%bd%bf%e7%94%a8swagger%e7%94%9f%e6%88%90api%e6%96%87%e6%a1%a3","status":"publish","type":"post","link":"https:\/\/docs.pingcode.com\/ask\/56360.html","title":{"rendered":"\u5982\u4f55\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863"},"content":{"rendered":"\n
\n

\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u9700\u7ecf\u5386\u4ee5\u4e0b\u5173\u952e\u6b65\u9aa4\uff1a1.\u4e3a\u9879\u76ee\u73af\u5883\u505a\u51c6\u5907\uff0c\u786e\u5b9a\u652f\u6301\u7684\u8bed\u8a00\u548c\u6846\u67b6\uff1b2.\u5b89\u88c5Swagger\u53ca\u76f8\u5173\u4f9d\u8d56\uff1b3. \u5b9a\u4e49API\u89c4\u8303\u548c\u6ce8\u89e3\uff1b4.\u81ea\u52a8\u751f\u6210API\u6587\u6863\uff1b5.\u9a8c\u8bc1API\u6587\u6863\u5e76\u8fdb\u884c\u7ef4\u62a4\u3002\u9996\u5148\uff0c\u786e\u4fdd\u4f60\u7684\u9879\u76ee\u73af\u5883\u4e0eSwagger\u517c\u5bb9\u3002<\/p>\n<\/blockquote>\n\n\n\n

1.\u4e3a\u9879\u76ee\u73af\u5883\u505a\u51c6\u5907\uff0c\u786e\u5b9a\u652f\u6301\u7684\u8bed\u8a00\u548c\u6846\u67b6<\/h2>\n\n\n\n

Swagger\u652f\u6301\u591a\u79cd\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\uff0c\u4eceJava, .NET, Node.js\u5230Ruby\u7b49\u3002\u9009\u62e9\u5bf9\u5e94\u4f60\u9879\u76ee\u7684Swagger\u7248\u672c\u548c\u5de5\u5177\u3002\u4e86\u89e3\u6240\u9700\u7684\u4f9d\u8d56\u548c\u7248\u672c\u517c\u5bb9\u6027\u975e\u5e38\u5173\u952e\u3002<\/p>\n\n\n\n

2.\u5b89\u88c5Swagger\u53ca\u76f8\u5173\u4f9d\u8d56<\/h2>\n\n\n\n

\u5b89\u88c5Swagger\u901a\u5e38\u9700\u8981\u5b89\u88c5\u4e00\u4e2aSwagger UI\u548c\u4e00\u4e2aSwagger Editor\u3002\u4f60\u4e5f\u53ef\u80fd\u9700\u8981Swagger Codegen\uff0c\u7279\u522b\u662f\u5982\u679c\u4f60\u5e0c\u671b\u4eceAPI\u5b9a\u4e49\u751f\u6210\u4ee3\u7801\u3002\u6839\u636e\u4f60\u7684\u5f00\u53d1\u73af\u5883\uff0c\u53ef\u4ee5\u901a\u8fc7\u5305\u7ba1\u7406\u5de5\u5177\u6216\u624b\u52a8\u4e0b\u8f7d\u548c\u5b89\u88c5\u3002\u4f8b\u5982\uff0cNode.js\u9879\u76ee\u53ef\u4ee5\u4f7f\u7528npm\uff0c\u800cJava\u9879\u76ee\u53ef\u80fd\u4f7f\u7528Maven\u6216Gradle\u3002<\/p>\n\n\n\n

3.\u5b9a\u4e49API\u89c4\u8303\u548c\u6ce8\u89e3<\/h2>\n\n\n\n

\u5f00\u59cb\u5b9a\u4e49API\u65f6\uff0c\u53ef\u4ee5\u4f7f\u7528Swagger Editor\u3002\u8fd9\u4e2a\u5de5\u5177\u63d0\u4f9b\u4e86\u4e00\u4e2a\u53cb\u597d\u7684\u754c\u9762\u6765\u5e2e\u52a9\u4f60\u5b9a\u4e49API\uff0c\u5e76\u63d0\u4f9b\u4e86\u5b9e\u65f6\u7684\u53cd\u9988\u548c\u9a8c\u8bc1\u3002\u5728API\u5b9a\u4e49\u4e2d\uff0c\u4f60\u9700\u8981\u4e3a\u6bcf\u4e00\u4e2aAPI\u7aef\u70b9\u63d0\u4f9b\u8be6\u7ec6\u7684\u63cf\u8ff0\u3001\u8bf7\u6c42\u53c2\u6570\u3001\u54cd\u5e94\u6a21\u578b\u7b49\u3002\u5982\u679c\u4f60\u7684\u9879\u76ee\u4e2d\u5df2\u7ecf\u4f7f\u7528\u4e86\u6ce8\u89e3\uff0c\u4f8b\u5982Javadoc\u6216.NET\u7684XML\u6ce8\u91ca\uff0c\u90a3\u4e48Swagger\u53ef\u4ee5\u81ea\u52a8\u63d0\u53d6\u8fd9\u4e9b\u4fe1\u606f\u5e76\u5c06\u5176\u7eb3\u5165API\u6587\u6863\u3002<\/p>\n\n\n\n

4.\u81ea\u52a8\u751f\u6210API\u6587\u6863<\/h2>\n\n\n\n

\u4e00\u65e6API\u89c4\u8303\u5b9a\u4e49\u5b8c\u6210\uff0c\u53ef\u4ee5\u4f7f\u7528Swagger UI\u81ea\u52a8\u751f\u6210API\u6587\u6863\u3002\u5b83\u4e3aAPI\u63d0\u4f9b\u4e86\u4e00\u4e2a\u4ea4\u4e92\u5f0f\u7684\u754c\u9762\uff0c\u8ba9\u7528\u6237\u53ef\u4ee5\u8f7b\u677e\u5730\u6d4f\u89c8\u3001\u6d4b\u8bd5API\u3002\u53ea\u9700\u786e\u4fddSwagger UI\u6307\u5411\u4e86\u4f60\u7684API\u5b9a\u4e49\u6587\u4ef6\u5373\u53ef\u3002<\/p>\n\n\n\n

5.\u9a8c\u8bc1API\u6587\u6863\u5e76\u8fdb\u884c\u7ef4\u62a4<\/h2>\n\n\n\n

\u5f53API\u6587\u6863\u751f\u6210\u540e\uff0c\u5efa\u8bae\u8fdb\u884c\u9a8c\u8bc1\u4ee5\u786e\u4fdd\u5176\u51c6\u786e\u6027\u548c\u5b8c\u6574\u6027\u3002\u53ef\u4ee5\u9080\u8bf7\u56e2\u961f\u6210\u5458\u6216\u5229\u76ca\u76f8\u5173\u8005\u8bc4\u5ba1\u6587\u6863\u3002\u5728\u9879\u76ee\u7684\u751f\u547d\u5468\u671f\u4e2d\uff0c\u5f53API\u53d1\u751f\u53d8\u5316\u65f6\uff0c\u4e5f\u9700\u8981\u66f4\u65b0Swagger\u5b9a\u4e49\u5e76\u91cd\u65b0\u751f\u6210\u6587\u6863\u3002<\/p>\n\n\n\n

Swagger\u7684\u5f15\u5165\u4e3aAPI\u5f00\u53d1\u5e26\u6765\u4e86\u5f88\u591a\u4fbf\u5229\uff0c\u4f46\u4e5f\u9700\u8981\u6301\u7eed\u7684\u7ef4\u62a4\u548c\u66f4\u65b0\u3002\u5b9a\u671f\u5ba1\u6838API\u6587\u6863\uff0c\u5e76\u786e\u4fdd\u5b83\u4e0e\u5b9e\u9645\u7684API\u5b9e\u73b0\u4fdd\u6301\u4e00\u81f4\u3002\u8fd9\u6837\uff0c\u4f60\u7684API\u6587\u6863\u4e0d\u4ec5\u4e3a\u5f00\u53d1\u8005\u63d0\u4f9b\u4e86\u5b9d\u8d35\u7684\u8d44\u6e90\uff0c\u4e5f\u786e\u4fdd\u4e86API\u7684\u900f\u660e\u6027\u548c\u4e00\u81f4\u6027\u3002<\/p>\n\n\n\n

\u603b\u7ed3\u800c\u8a00\uff0c\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u662f\u4e00\u4e2a\u7ed3\u6784\u5316\u7684\u8fc7\u7a0b\uff0c\u9700\u8981\u660e\u786e\u6b65\u9aa4\u3001\u6301\u7eed\u7ef4\u62a4\u5e76\u786e\u4fdd\u4e0eAPI\u5b9e\u73b0\u540c\u6b65\u3002\u6709\u6548\u7684API\u6587\u6863\u80fd\u591f\u63d0\u9ad8\u5f00\u53d1\u6548\u7387\uff0c\u4fc3\u8fdb\u56e2\u961f\u4e4b\u95f4\u7684\u6c9f\u901a\uff0c\u540c\u65f6\u4e5f\u80fd\u4e3aAPI\u6d88\u8d39\u8005\u63d0\u4f9b\u66f4\u597d\u7684\u4f53\u9a8c\u3002<\/p>\n\n\n

\n
\"\"<\/figure><\/div>\n\n\n

\u5e38\u89c1\u95ee\u7b54<\/strong><\/p>\n\n\n\n

    \n
  • \u95ee\uff1a\u4ec0\u4e48\u662fSwagger\uff0c\u5b83\u5728API\u6587\u6863\u4e2d\u7684\u4f5c\u7528\u662f\u4ec0\u4e48\uff1f<\/li>\n\n\n\n
  • \u7b54\uff1aSwagger\u662f\u4e00\u4e2a\u5f3a\u5927\u7684API\u6587\u6863\u751f\u6210\u5de5\u5177\u3002\u5b83\u4e0d\u4ec5\u80fd\u591f\u81ea\u52a8\u5730\u751f\u6210API\u7684\u6587\u6863\u8bf4\u660e\uff0c\u4f7f\u5f97API\u7684\u5f00\u53d1\u3001\u6d4b\u8bd5\u53d8\u5f97\u7b80\u6d01\u660e\u4e86\uff0c\u8fd8\u80fd\u4f7f\u5f00\u53d1\u8005\u80fd\u591f\u901a\u8fc7API\u6587\u6863\u66f4\u597d\u5730\u7406\u89e3\u548c\u4f7f\u7528API\u3002\u5176\u81ea\u52a8\u5316\u7684\u6587\u6863\u66f4\u65b0\u529f\u80fd\u51cf\u5c11\u4e86\u624b\u52a8\u7f16\u5199API\u6587\u6863\u7684\u5de5\u4f5c\u91cf\uff0c\u5e76\u4e14\u4fdd\u6301\u6587\u6863\u4e0eAPI\u7684\u540c\u6b65\u66f4\u65b0\u3002<\/li>\n<\/ul>\n\n\n\n
      \n
    • \u95ee\uff1a\u5982\u4f55\u5728\u5df2\u6709\u7684\u9879\u76ee\u4e2d\u5f15\u5165\u5e76\u914d\u7f6eSwagger\uff1f<\/li>\n\n\n\n
    • \u7b54\uff1a\u5728\u5927\u591a\u6570\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\u4e2d\uff0c\u5f15\u5165Swagger\u901a\u5e38\u6d89\u53ca\u6dfb\u52a0Swagger\u7684\u5e93\u6216\u4f9d\u8d56\uff0c\u5e76\u8fdb\u884c\u4e00\u4e9b\u57fa\u672c\u914d\u7f6e\u3002\u4f8b\u5982\uff0c\u5728\u4e00\u4e2a\u57fa\u4e8eSpring Boot\u7684Java\u9879\u76ee\u4e2d\uff0c\u4f60\u9700\u8981\u6dfb\u52a0Swagger\u7684\u4f9d\u8d56\u5230\u4f60\u7684`pom.xml`\u6587\u4ef6\u4e2d\uff0c\u5e76\u5728\u9879\u76ee\u4e2d\u521b\u5efa\u4e00\u4e2a\u914d\u7f6e\u7c7b\uff0c\u4f7f\u7528`@EnableSwagger2`\u6ce8\u89e3\u6765\u542f\u52a8Swagger\uff0c\u5e76\u901a\u8fc7`@Bean`\u6ce8\u89e3\u521b\u5efa\u4e00\u4e2a`Docket`\u5b9e\u4f8b\u6765\u914d\u7f6eAPI\u6587\u6863\u7684\u4fe1\u606f\uff0c\u5982API\u7684\u7248\u672c\u3001\u63cf\u8ff0\u7b49\u4fe1\u606f\u3002<\/li>\n<\/ul>\n\n\n\n
        \n
      • \u95ee\uff1aSwagger\u652f\u6301\u54ea\u4e9b\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\uff1f<\/li>\n\n\n\n
      • \u7b54\uff1aSwagger\u63d0\u4f9b\u4e86\u5e7f\u6cdb\u7684\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\u652f\u6301\u3002\u5e38\u89c1\u7684\u5982Java\u7684Spring\u6846\u67b6\u3001Python\u7684Flask\u548cFastAPI\u6846\u67b6\u3001Node.js\u7684Express\u6846\u67b6\u7b49\u90fd\u80fd\u591f\u5f88\u597d\u5730\u4e0eSwagger\u96c6\u6210\u3002Swagger\u63d0\u4f9b\u4e86\u5404\u79cd\u8bed\u8a00\u7684\u5e93\u548c\u5de5\u5177\u6765\u5e2e\u52a9\u5f00\u53d1\u8005\u5728\u4e0d\u540c\u7684\u73af\u5883\u4e0b\u751f\u6210API\u6587\u6863\u3002<\/li>\n<\/ul>\n\n\n\n
          \n
        • \u95ee\uff1a\u5728\u4f7f\u7528Swagger\u65f6\uff0c\u5982\u4f55\u6dfb\u52a0API\u7684\u57fa\u672c\u4fe1\u606f\u548c\u63cf\u8ff0\uff1f<\/li>\n\n\n\n
        • \u7b54\uff1a\u901a\u8fc7Swagger\u914d\u7f6e\u6587\u4ef6\u6216\u914d\u7f6e\u5bf9\u8c61\uff0c\u4f60\u53ef\u4ee5\u4e3aAPI\u6587\u6863\u6dfb\u52a0\u4e00\u4e9b\u57fa\u672c\u4fe1\u606f\uff0c\u4f8b\u5982API\u7684\u6807\u9898\u3001\u63cf\u8ff0\u3001\u7248\u672c\u3001\u8054\u7cfb\u4eba\u4fe1\u606f\u7b49\u3002\u5728\u5f88\u591a\u6846\u67b6\u4e2d\uff0c\u4f60\u53ef\u4ee5\u901a\u8fc7\u5728\u914d\u7f6e\u7c7b\u4e2d\u7684`Docket`\u5b9e\u4f8b\u4e2d\u8bbe\u7f6e`apiInfo`\u65b9\u6cd5\u6765\u6dfb\u52a0API\u7684\u57fa\u672c\u4fe1\u606f\u3002`apiInfo`\u65b9\u6cd5\u901a\u5e38\u63a5\u53d7\u4e00\u4e2a`ApiInfo`\u5b9e\u4f8b\uff0c\u8be5\u5b9e\u4f8b\u4e2d\u53ef\u4ee5\u5305\u542bAPI\u7684\u6807\u9898\u3001\u63cf\u8ff0\u3001\u7248\u672c\u7b49\u4fe1\u606f\u3002<\/li>\n<\/ul>\n\n\n\n
            \n
          • \u95ee\uff1aSwagger\u751f\u6210\u7684API\u6587\u6863\u53ef\u4ee5\u88ab\u5bfc\u51fa\u5417\uff1f<\/li>\n\n\n\n
          • \u7b54\uff1a\u662f\u7684\uff0cSwagger\u751f\u6210\u7684API\u6587\u6863\u652f\u6301\u591a\u79cd\u683c\u5f0f\u7684\u5bfc\u51fa\uff0c\u4f8b\u5982HTML\u3001PDF\u3001Word\u7b49\u3002\u4f60\u53ef\u4ee5\u4f7f\u7528Swagger UI\u8fdb\u884c\u5728\u7ebf\u67e5\u770b\uff0c\u4e5f\u53ef\u4ee5\u4f7f\u7528Swagger Codegen\u6216\u5176\u4ed6\u7b2c\u4e09\u65b9\u5de5\u5177\u6765\u5bfc\u51faAPI\u6587\u6863\u5230\u4e0d\u540c\u683c\u5f0f\u7684\u6587\u4ef6\u3002\u8fd9\u8ba9API\u6587\u6863\u80fd\u591f\u5f88\u65b9\u4fbf\u5730\u5206\u4eab\u7ed9\u6ca1\u6709\u8bbf\u95ee\u5728\u7ebf\u6587\u6863\u7684\u5f00\u53d1\u8005\u6216\u8005\u4f7f\u7528\u8005\u3002<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u9700\u7ecf\u5386\u4ee5\u4e0b\u5173\u952e\u6b65\u9aa4\uff1a1.\u4e3a\u9879\u76ee\u73af\u5883\u505a\u51c6\u5907\uff0c\u786e\u5b9a\u652f\u6301\u7684\u8bed\u8a00\u548c\u6846\u67b6\uff1b2.\u5b89\u88c5Swa […]","protected":false},"author":3,"featured_media":56362,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[37],"tags":[2651,2652],"acf":[],"_links":{"self":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/posts\/56360"}],"collection":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/comments?post=56360"}],"version-history":[{"count":0,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/posts\/56360\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/media\/56362"}],"wp:attachment":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/media?parent=56360"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/categories?post=56360"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/tags?post=56360"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}