{"id":98681,"date":"2024-04-12T11:21:59","date_gmt":"2024-04-12T03:21:59","guid":{"rendered":"https:\/\/docs.pingcode.com\/ask\/ask-ask\/98681.html"},"modified":"2024-04-12T11:22:00","modified_gmt":"2024-04-12T03:22:00","slug":"java%e9%a1%b9%e7%9b%ae%e6%80%8e%e4%b9%88%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\/ask-ask\/98681.html","title":{"rendered":"Java\u9879\u76ee\u600e\u4e48\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863"},"content":{"rendered":"

\"Java\u9879\u76ee\u600e\u4e48\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\"<\/p>\n

Swagger\u662f\u4e00\u4e2a\u89c4\u8303\u548c\u5b8c\u6574\u7684\u6846\u67b6\uff0c\u7528\u4e8e\u751f\u6210\u3001\u63cf\u8ff0\u3001\u8c03\u7528\u548c\u53ef\u89c6\u5316RESTful\u98ce\u683c\u7684Web\u670d\u52a1\u3002\u603b\u4f53\u76ee\u6807\u662f\u4f7f\u5ba2\u6237\u7aef\u548c\u6587\u4ef6\u7cfb\u7edf\u4f5c\u4e3a\u670d\u52a1\u5668\u4ee5\u540c\u6837\u7684\u901f\u5ea6\u6765\u66f4\u65b0\u3002\u6587\u4ef6\u7684\u65b9\u6cd5\u3001\u53c2\u6570\u548c\u6a21\u578b\u7d27\u5bc6\u96c6\u6210\u5230\u670d\u52a1\u5668\u7aef\u7684\u4ee3\u7801\uff0c\u5141\u8bb8API\u6765\u59cb\u7ec8\u4fdd\u6301\u540c\u6b65\u3002Java\u9879\u76ee\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u7684\u6b65\u9aa4\u4e3b\u8981\u5305\u62ec\u6dfb\u52a0Swagger\u4f9d\u8d56\u3001\u914d\u7f6eSwagger\u3001\u6ce8\u89e3\u7684\u4f7f\u7528<\/strong>\u7b49\uff0c\u4e0b\u9762\u5bf9\u5982\u4f55\u914d\u7f6eSwagger\u8fdb\u884c\u8be6\u7ec6\u63cf\u8ff0\u3002<\/p>\n<\/p>\n

\u9996\u5148\uff0c\u60a8\u9700\u8981\u5728\u9879\u76ee\u7684\u6784\u5efa\u914d\u7f6e\u6587\u4ef6\u4e2d\u52a0\u5165Swagger\u7684\u4f9d\u8d56\u3002\u5bf9\u4e8eMaven\u9879\u76ee\uff0c\u53ef\u4ee5\u5728pom.xml<\/code>\u4e2d\u6dfb\u52a0\u4ee5\u4e0b\u4f9d\u8d56\uff08\u4ee5Spring Boot\u9879\u76ee\u4e3a\u4f8b\uff09\uff1a<\/p>\n<\/p>\n

<!-- Swagger\u4f9d\u8d56 --><\/p>\n
<dependency><\/p>\n
    <groupId>io.springfox<\/groupId><\/p>\n
    <artifactId>springfox-swagger2<\/artifactId><\/p>\n
    <version>2.9.2<\/version><\/p>\n
<\/dependency><\/p>\n
<dependency><\/p>\n
    <groupId>io.springfox<\/groupId><\/p>\n
    <artifactId>springfox-swagger-ui<\/artifactId><\/p>\n
    <version>2.9.2<\/version><\/p>\n
<\/dependency><\/p>\n
<\/code><\/pre>\n<\/p>\n
\u5bf9\u4e8eGradle\u9879\u76ee\uff0c\u5219\u5728build.gradle<\/code>\u6587\u4ef6\u4e2d\u6dfb\u52a0\u7c7b\u4f3c\u4f9d\u8d56\u3002<\/p>\n<\/p>\n
\u6dfb\u52a0\u5b8c\u4f9d\u8d56\u540e\uff0c\u9700\u8981\u521b\u5efa\u4e00\u4e2a\u914d\u7f6e\u7c7b\u4e3aSpring\u5bb9\u5668\u6dfb\u52a0Swagger\u7684\u914d\u7f6e\u4fe1\u606f\u3002\u8fd9\u4e2a\u914d\u7f6e\u7c7b\u5b9a\u4e49\u4e86Swagger\u626b\u63cf\u7684\u5305\u8def\u5f84\u3001API\u7684\u57fa\u672c\u4fe1\u606f\uff08\u5982\u7248\u672c\u3001\u6807\u9898\u3001\u63cf\u8ff0\uff09\u3001\u5b89\u5168\u914d\u7f6e\u3001\u5168\u5c40\u54cd\u5e94\u6d88\u606f\u7b49\u3002<\/p>\n<\/p>\n
\u63a5\u7740\uff0c\u53ef\u4ee5\u4f7f\u7528Swagger\u6ce8\u89e3\u6765\u7cbe\u786e\u5730\u63cf\u8ff0API\u7684\u7ec6\u8282\uff0c\u5982@ApiOperation<\/code>\u6ce8\u89e3\u63d0\u4f9b\u65b9\u6cd5\u7684\u7b80\u8981\u63cf\u8ff0\uff0c@ApiParam<\/code>\u6ce8\u89e3\u63cf\u8ff0\u53c2\u6570\u7ec6\u8282\u7b49\u3002<\/p>\n<\/p>\n
\u4f7f\u7528\u4ee5\u4e0a\u6b65\u9aa4\u914d\u7f6e\u597dSwagger\u540e\uff0c\u5728\u9879\u76ee\u542f\u52a8\u65f6\uff0cSwagger\u4f1a\u626b\u63cf\u76f8\u5e94\u7684\u6ce8\u89e3\u5e76\u81ea\u52a8\u751f\u6210API\u6587\u6863\uff0c\u5b83\u4eec\u53ef\u4ee5\u901a\u8fc7\u8bbf\u95ee\u914d\u7f6e\u7684URL\u8def\u5f84\u5728\u6d4f\u89c8\u5668\u4e2d\u67e5\u770b\u548c\u4ea4\u4e92\u3002<\/p>\n<\/p>\n
\u4e00\u3001\u914d\u7f6eSwagger<\/h3>\n<\/p>\n
\u786e\u5b9aAPI\u7248\u672c\u548c\u8def\u5f84<\/h4>\n<\/p>\n
\u521b\u5efa\u4e00\u4e2a\u914d\u7f6e\u7c7b\uff0c\u901a\u8fc7@EnableSwagger2<\/code>\u6ce8\u89e3\u5f00\u542fSwagger\uff0c\u5e76\u4f7f\u7528@Configuration<\/code>\u6ce8\u89e3\u6807\u8bc6\u5176\u4e3a\u914d\u7f6e\u7c7b\u3002\u5728\u8fd9\u4e2a\u7c7b\u4e2d\uff0c\u53ef\u4ee5\u521b\u5efa\u4e00\u4e2aDocket<\/code> Bean\u6765\u914d\u7f6eSwagger\u7684\u5177\u4f53\u53c2\u6570\uff0c\u6bd4\u5982API\u7684\u7248\u672c\u4fe1\u606f\u3001API\u7684\u57fa\u672c\u4fe1\u606f\u3001\u9009\u62e9\u54ea\u4e9b\u8def\u5f84\u548capi\u4f1a\u751f\u6210document\u3002<\/p>\n<\/p>\n
\u8bbe\u7f6eAPI\u7684\u57fa\u672c\u4fe1\u606f<\/h4>\n<\/p>\n
\u4f7f\u7528apiInfo()<\/code>\u65b9\u6cd5\u914d\u7f6e\u6587\u6863\u9875\u7684\u57fa\u672c\u4fe1\u606f\uff0c\u8fd9\u91cc\u53ef\u4ee5\u8bbe\u7f6e\u6807\u9898\u3001\u63cf\u8ff0\u3001\u670d\u52a1\u6761\u6b3e\u7684URL\u3001\u8054\u7cfb\u4fe1\u606f\u7b49\u3002<\/p>\n<\/p>\n
\u4e8c\u3001Swagger\u6ce8\u89e3\u7684\u4f7f\u7528<\/h3>\n<\/p>\n
Swagger\u63d0\u4f9b\u4e86\u4e00\u7cfb\u5217\u7684\u6ce8\u89e3\u7528\u4e8e\u63cf\u8ff0\u548c\u7ba1\u7406API\u3002<\/p>\n<\/p>\n
\u63cf\u8ff0\u63a7\u5236\u5668\u548c\u65b9\u6cd5<\/h4>\n<\/p>\n
@Api<\/code>\u7528\u4e8e\u7c7b\u4e0a\uff0c\u8868\u660e\u8fd9\u4e2a\u7c7b\u662fswagger\u7684\u8d44\u6e90\uff1b@ApiOperation<\/code>\u7528\u4e8e\u65b9\u6cd5\u4e0a\uff0c\u63cf\u8ff0\u4e00\u4e2a\u7c7b\u7684\u4e00\u4e2a\u65b9\u6cd5\u6216\u8005\u8bf4\u4e00\u4e2a\u63a5\u53e3\u3002<\/p>\n<\/p>\n
\u63cf\u8ff0\u53c2\u6570<\/h4>\n<\/p>\n
@ApiParam<\/code>\u8be6\u7ec6\u5730\u63cf\u8ff0\u4e86\u4e00\u4e2a\u53c2\u6570\u7684\u5404\u4e2a\u65b9\u9762\uff0c\u5982\u540d\u79f0\u3001\u503c\u7684\u8303\u56f4\u7b49\u3002<\/p>\n<\/p>\n
\u4e09\u3001\u5b89\u5168\u548c\u6743\u9650\u7684\u914d\u7f6e<\/h3>\n<\/p>\n
\u5728\u4e00\u4e9b\u9700\u8981\u8fdb\u884c\u6743\u9650\u6821\u9a8c\u7684API\u63a5\u53e3\uff0c\u53ef\u4ee5\u901a\u8fc7Swagger\u7684\u5b89\u5168\u5b9a\u4e49\u6765\u914d\u7f6eAPI\u7684\u8ba4\u8bc1\u673a\u5236\u3002<\/p>\n<\/p>\n
\u914d\u7f6e\u5b89\u5168\u6a21\u5f0f<\/h4>\n<\/p>\n
\u4f7f\u7528securitySchemes()<\/code>\u914d\u7f6e\u5168\u5c40\u7684\u8ba4\u8bc1\u65b9\u5f0f\uff0c\u5982\u6dfb\u52a0API Key\u6216\u8005\u914d\u7f6eOAuth2.0\u3002<\/p>\n<\/p>\n
\u8bbe\u7f6e\u7528\u4e8eAPI\u7684\u8ba4\u8bc1\u4fe1\u606f<\/h4>\n<\/p>\n
\u901a\u8fc7securityContexts()<\/code>\u65b9\u6cd5\u6765\u4f7f\u7528\u914d\u7f6e\u597d\u7684\u5b89\u5168\u6a21\u5f0f\u3002<\/p>\n<\/p>\n
\u56db\u3001\u81ea\u5b9a\u4e49\u5168\u5c40\u54cd\u5e94\u6d88\u606f<\/h3>\n<\/p>\n
Swagger\u5141\u8bb8\u6211\u4eec\u81ea\u5b9a\u4e49\u5168\u5c40\u7684\u54cd\u5e94\u6d88\u606f\u3002<\/p>\n<\/p>\n
\u66ff\u6362\u9ed8\u8ba4\u54cd\u5e94\u6d88\u606f<\/h4>\n<\/p>\n
\u901a\u8fc7useDefaultResponseMessages(false)<\/code>\u5173\u95ed\u9ed8\u8ba4\u7684\u54cd\u5e94\u6d88\u606f\uff0c\u7136\u540e\u901a\u8fc7\u5168\u5c40\u54cd\u5e94\u6d88\u606f\u65b9\u6cd5\u6765\u5b9a\u4e49\u5168\u5c40\u6d88\u606f\u3002<\/p>\n<\/p>\n
\u6dfb\u52a0\u81ea\u5b9a\u4e49\u54cd\u5e94\u6d88\u606f<\/h4>\n<\/p>\n
\u4f7f\u7528globalResponseMessage()<\/code>\u65b9\u6cd5\u6765\u6dfb\u52a0\u81ea\u5b9a\u4e49\u54cd\u5e94\u6d88\u606f\u3002<\/p>\n<\/p>\n
\u4e94\u3001\u6574\u5408Swagger\u548c\u5176\u4ed6Spring\u7ec4\u4ef6<\/h3>\n<\/p>\n
Swagger\u80fd\u591f\u4e0eSpring\u7684\u5176\u4ed6\u7ec4\u4ef6\u5982Spring Security\u7ed3\u5408\u4f7f\u7528\uff0c\u5b9e\u73b0\u66f4\u52a0\u5b8c\u5584\u7684\u6587\u6863\u7ba1\u7406\u3002<\/p>\n<\/p>\n
\u4e0eSpring Security\u6574\u5408<\/h4>\n<\/p>\n
\u8981\u8ba9Swagger\u77e5\u9053\u54ea\u4e9bAPI\u662f\u53d7\u4fdd\u62a4\u7684\uff0c\u53ef\u4ee5\u5728Spring Security\u7684\u914d\u7f6e\u4e2d\u5bf9Swagger\u7684\u8d44\u6e90\u8def\u5f84\u8fdb\u884c\u653e\u884c\u3002<\/p>\n<\/p>\n
\u6ce8\u89e3\u7684\u6761\u4ef6\u5316<\/h4>\n<\/p>\n
\u5728\u67d0\u4e9b\u60c5\u51b5\u4e0b\uff0c\u53ef\u4ee5\u4f7f\u7528@Profile<\/code>\u6ce8\u89e3\u6765\u8ba9Swagger\u7684\u914d\u7f6e\u5728\u5f00\u53d1\u73af\u5883\u4e2d\u542f\u7528\uff0c\u5728\u751f\u4ea7\u73af\u5883\u4e2d\u5173\u95ed\u3002<\/p>\n<\/p>\n
\u672c\u6587\u5df2\u8be6\u7ec6\u63cf\u8ff0\u4e86Java\u9879\u76ee\u5982\u4f55\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\uff0c\u91cd\u70b9\u5728\u4e8e\u5982\u4f55\u901a\u8fc7\u6dfb\u52a0\u4f9d\u8d56\u3001\u914d\u7f6eSwagger\u3001\u4f7f\u7528\u6ce8\u89e3\u548c\u6574\u5408\u5176\u4ed6Spring\u7ec4\u4ef6\u6765\u8fbe\u5230\u81ea\u52a8\u751f\u6210\u548c\u7ba1\u7406API\u6587\u6863\u7684\u76ee\u7684\u3002<\/p>\n<\/p>\n
\u76f8\u5173\u95ee\u7b54FAQs\uff1a<\/strong><\/h2>\n
\u4e3a\u4ec0\u4e48\u8981\u4f7f\u7528Swagger\u6765\u751f\u6210Java\u9879\u76ee\u7684API\u6587\u6863\uff1f<\/strong><\/p>\n
Swagger\u662f\u4e00\u4e2a\u5f3a\u5927\u7684\u5de5\u5177\uff0c\u53ef\u4ee5\u81ea\u52a8\u5316\u5730\u751f\u6210API\u6587\u6863\uff0c\u80fd\u591f\u63d0\u9ad8Java\u9879\u76ee\u7684\u5f00\u53d1\u6548\u7387\uff0c\u63d0\u5347\u56e2\u961f\u7684\u534f\u4f5c\u80fd\u529b\uff0c\u540c\u65f6\u4e5f\u80fd\u591f\u63d0\u4f9b\u7ed9\u5176\u4ed6\u5f00\u53d1\u8005\u4e00\u4e2a\u6e05\u6670\u3001\u6613\u8bfb\u7684\u63a5\u53e3\u6587\u6863\uff0c\u65b9\u4fbf\u5176\u4f7f\u7528\u3002<\/p>\n
\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u6709\u54ea\u4e9b\u6b65\u9aa4\uff1f<\/strong><\/p>\n
\u9996\u5148\uff0c\u9700\u8981\u5728Java\u9879\u76ee\u4e2d\u5f15\u5165Swagger\u7684\u4f9d\u8d56\u3002\u53ef\u4ee5\u4f7f\u7528Maven\u6216Gradle\u7b49\u6784\u5efa\u5de5\u5177\uff0c\u5728\u9879\u76ee\u7684pom.xml\u6216build.gradle\u6587\u4ef6\u4e2d\u6dfb\u52a0Swagger\u76f8\u5173\u7684\u4f9d\u8d56\u9879\u3002<\/p>\n
\u63a5\u7740\uff0c\u5728Java\u63a5\u53e3\u7684\u5b9e\u73b0\u7c7b\u6216\u63a7\u5236\u5668\u4e0a\u4f7f\u7528Swagger\u7684\u6ce8\u89e3\u6765\u63cf\u8ff0\u63a5\u53e3\u4fe1\u606f\uff0c\u4f8b\u5982@Api\u3001@ApiOperation\u3001@ApiParam\u7b49\uff0c\u8fd9\u4e9b\u6ce8\u89e3\u80fd\u591f\u6307\u5b9a\u63a5\u53e3\u7684\u540d\u79f0\u3001\u63cf\u8ff0\u3001\u53c2\u6570\u7b49\u8be6\u7ec6\u4fe1\u606f\u3002<\/p>\n
\u7136\u540e\uff0c\u542f\u52a8Java\u9879\u76ee\uff0c\u5e76\u8bbf\u95eeSwagger\u7684UI\u754c\u9762\uff0c\u4e00\u822c\u662f\u901a\u8fc7\u8bbf\u95eeURL http:\/\/localhost:port\/swagger-ui.html<\/a> \u6765\u6253\u5f00Swagger\u7684UI\u754c\u9762\uff0c\u5176\u4e2dport\u662f\u9879\u76ee\u8fd0\u884c\u7684\u7aef\u53e3\u53f7\u3002<\/p>\n
\u6700\u540e\uff0c\u53ef\u4ee5\u5728Swagger\u7684UI\u754c\u9762\u4e2d\u67e5\u770b\u5e76\u6d4b\u8bd5API\u63a5\u53e3\uff0c\u8fd8\u53ef\u4ee5\u5bfc\u51fa\u63a5\u53e3\u6587\u6863\uff0c\u751f\u6210PDF\u6216HTML\u683c\u5f0f\u7684\u6587\u6863\u6587\u4ef6\u3002<\/p>\n
\u5982\u4f55\u5b9e\u73b0Java\u9879\u76ee\u4e2dSwagger\u751f\u6210\u7684API\u6587\u6863\u7684\u5b9e\u65f6\u66f4\u65b0\uff1f<\/strong><\/p>\n
\u8981\u5b9e\u73b0Java\u9879\u76ee\u4e2dSwagger\u751f\u6210\u7684API\u6587\u6863\u7684\u5b9e\u65f6\u66f4\u65b0\uff0c\u53ef\u4ee5\u4f7f\u7528Swagger\u63d0\u4f9b\u7684\u81ea\u52a8\u66f4\u65b0\u529f\u80fd\u3002\u5728Java\u9879\u76ee\u4e2d\u914d\u7f6eSwagger\u7684\u626b\u63cf\u8def\u5f84\uff0c\u6307\u5b9a\u9700\u8981\u626b\u63cf\u7684\u5305\u8def\u5f84\uff0c\u5e76\u8bbe\u7f6e\u5b9a\u65f6\u4efb\u52a1\u6216\u76d1\u542c\u5668\uff0c\u5b9a\u65f6\u6216\u76d1\u542c\u5305\u4e0b\u7684\u7c7b\u6587\u4ef6\u7684\u53d8\u5316\u3002<\/p>\n
\u5f53Java\u9879\u76ee\u4e2d\u7684\u63a5\u53e3\u6a21\u5757\u6709\u53d8\u52a8\u65f6\uff0cSwagger\u4f1a\u81ea\u52a8\u68c0\u6d4b\u5230\u53d8\u5316\uff0c\u5e76\u91cd\u65b0\u751f\u6210API\u6587\u6863\u3002\u8fd9\u6837\u53ef\u4ee5\u4fdd\u8bc1API\u6587\u6863\u7684\u5b9e\u65f6\u66f4\u65b0\uff0c\u4e0e\u5b9e\u9645\u4ee3\u7801\u4fdd\u6301\u4e00\u81f4\u3002\u540c\u65f6\uff0c\u4e5f\u53ef\u4ee5\u901a\u8fc7\u8bbe\u7f6eSwagger\u7684\u7f13\u5b58\u65f6\u95f4\u6765\u63a7\u5236\u6587\u6863\u7684\u5237\u65b0\u9891\u7387\uff0c\u907f\u514d\u9891\u7e41\u7684\u91cd\u590d\u751f\u6210\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"Swagger\u662f\u4e00\u4e2a\u89c4\u8303\u548c\u5b8c\u6574\u7684\u6846\u67b6\uff0c\u7528\u4e8e\u751f\u6210\u3001\u63cf\u8ff0\u3001\u8c03\u7528\u548c\u53ef\u89c6\u5316RESTful\u98ce\u683c\u7684Web\u670d\u52a1\u3002\u603b\u4f53\u76ee\u6807\u662f\u4f7f […]","protected":false},"author":3,"featured_media":98683,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[37],"tags":[],"acf":[],"_links":{"self":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/posts\/98681"}],"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=98681"}],"version-history":[{"count":0,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/posts\/98681\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/media\/98683"}],"wp:attachment":[{"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/media?parent=98681"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/categories?post=98681"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/docs.pingcode.com\/wp-json\/wp\/v2\/tags?post=98681"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}