{"id":23253,"date":"2024-11-21T08:24:36","date_gmt":"2024-11-21T00:24:36","guid":{"rendered":"https:\/\/fwq.ai\/blog\/23253\/"},"modified":"2024-11-21T08:24:36","modified_gmt":"2024-11-21T00:24:36","slug":"%e6%80%8e%e6%a0%b7%e4%bd%bf%e7%94%a8swagger%e7%94%9f%e6%88%90api%e6%96%87%e6%a1%a3%ef%bc%9f","status":"publish","type":"post","link":"https:\/\/fwq.ai\/blog\/23253\/","title":{"rendered":"\u600e\u6837\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\uff1f"},"content":{"rendered":"

\u968f\u7740web\u5e94\u7528\u7a0b\u5e8f\u7684\u5feb\u901f\u53d1\u5c55\uff0capi\u6587\u6863\u8d8a\u6765\u8d8a\u91cd\u8981\u3002api\u6587\u6863\u65e8\u5728\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u7406\u89e3api\u7684\u4f7f\u7528\u65b9\u6cd5\u548c\u53c2\u6570\uff0c\u51cf\u5c11\u65f6\u95f4\u548c\u8d44\u6e90\u6d6a\u8d39\u3002\u7136\u800c\uff0c\u624b\u52a8\u7f16\u5199api\u6587\u6863\u53ef\u80fd\u4f1a\u5f88\u9ebb\u70e6\u4e14\u8d39\u65f6\uff0c\u8fd9\u65f6\u5019swagger\u5219\u6210\u4e3a\u4e86\u5f00\u53d1\u4eba\u5458\u7684\u5229\u5668\u3002swagger\u662f\u4e00\u79cd\u6d41\u884c\u7684api\u6587\u6863\u5de5\u5177\uff0c\u53ef\u4ee5\u81ea\u52a8\u5316\u751f\u6210\u53ef\u8bfb\u6027\u5f3a\uff0c\u4ea4\u4e92\u6027\u7684api\u6587\u6863\u3002\u5728\u672c\u6587\u4e2d\uff0c\u6211\u4eec\u4ecb\u7ecd\u4e86\u5982\u4f55\u4f7f\u7528swagger\u6765\u81ea\u52a8\u751f\u6210api\u6587\u6863\u3002<\/p>\n

\u4ec0\u4e48\u662fSwagger\uff1f<\/p>\n

Swagger\u662f\u4e00\u7ec4\u5f00\u6e90\u5de5\u5177\uff0c\u53ef\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u6784\u5efa\uff0c\u8bbe\u8ba1\uff0c\u63cf\u8ff0\u548c\u4f7f\u7528RESTful Web\u670d\u52a1\u3002 Swagger\u5141\u8bb8\u60a8\u4f7f\u7528\u7528\u4e8e\u63cf\u8ff0API\u64cd\u4f5c\u7684YAML\u6216JSON\u683c\u5f0f\u7f16\u5199API\u6587\u6863\uff0c\u5e76\u751f\u6210\u6613\u4e8e\u9605\u8bfb\u548c\u4ea4\u4e92\u7684\u63a5\u53e3\u6587\u6863\u3002<\/p>\n

Swagger\u652f\u6301\u591a\u79cd\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\uff0c\u4f8b\u5982Java\uff0cC\uff03\uff0cPython\u548cRuby\u3002\u5b83\u8fd8\u53ef\u4ee5\u4e0e\u8bb8\u591a\u73b0\u6709\u7684API\u6846\u67b6\u8fdb\u884c\u96c6\u6210\uff0c\u5305\u62ecSpring\uff0cExpress\u548cDjango\u7b49\u3002<\/p>\n

\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u9700\u8981\u5148\u5b89\u88c5Swagger UI\u3002Swagger UI\u662f\u4e00\u4e2a\u4ea4\u4e92\u5f0fAPI\u6587\u6863\u7f51\u7ad9\uff0c\u72ec\u7acb\u4e8eAPI\uff0c\u5e76\u8ddf\u968fSwagger\u89c4\u8303\u3002\u5b83\u63d0\u4f9b\u4e86API\u6587\u6863\u53ef\u89c6\u5316\u7684\u6f02\u4eae\u754c\u9762\uff0c\u5e76\u652f\u6301\u81ea\u52a8\u5316\u5c1d\u8bd5API\u8c03\u7528\u3002<\/p>\n

\u6b65\u9aa41\uff1a\u914d\u7f6eSwagger<\/p>\n

\u8981\u4f7f\u7528Swagger\uff0c\u9700\u8981\u5148\u4e0b\u8f7dSwagger\u5305\uff0c\u53ef\u4ee5\u4eceSwagger\u7f51\u7ad9\u83b7\u53d6\u6216\u4f7f\u7528\u4f9d\u8d56\u7ba1\u7406\u5668\u8fdb\u884c\u4e0b\u8f7d\u3002<\/p>\n

\u5728Java Spring Boot\u9879\u76ee\u4e2d\u914d\u7f6eSwagger API\uff0c\u9700\u8981\u5728maven\u4f9d\u8d56\u4e2d\u6dfb\u52a0\u4ee5\u4e0bSwagger\u4f9d\u8d56\uff1a<\/p>\n

<dependency><groupid>io.springfox<\/groupid><artifactid>springfox-swagger2<\/artifactid><version>${springfox-swagger2.version}<\/version><\/dependency><dependency><groupid>io.springfox<\/groupid><artifactid>springfox-swagger-ui<\/artifactid><version>${springfox-swagger-ui.version}<\/version><\/dependency><\/pre>\n
  \u767b\u5f55\u540e\u590d\u5236   <\/p>\n
\u5176\u4e2d${springfox-swagger2.version}\u548c${springfox-swagger-ui.version}\u4ee3\u8868Swagger\u7248\u672c\u53f7\u3002 \u914d\u7f6e\u6587\u4ef6application.properties\u4e2d\u5f00\u542fswagger\uff1a<\/p>\n
#\u5f00\u542fswagger\nswagger.enabled = true<\/pre>\n
  \u767b\u5f55\u540e\u590d\u5236   <\/p>\n
\u6b65\u9aa42\uff1a\u7f16\u5199Swagger\u6ce8\u89e3<\/p>\n
Swagger\u4f7f\u7528\u6ce8\u89e3\u6765\u63cf\u8ff0API\u4e2d\u7684\u64cd\u4f5c\u548c\u53c2\u6570\u3002\u5728API\u63a7\u5236\u5668\u7c7b\u548c\u5176\u65b9\u6cd5\u7684\u9876\u90e8\u6dfb\u52a0Swagger\u6ce8\u89e3\uff0c\u4ee5\u4fbfSwagger\u80fd\u591f\u6b63\u786e\u5730\u89e3\u6790\u548c\u751f\u6210\u6587\u6863\u5e76\u5728Swagger UI\u4e0a\u663e\u793a\u3002<\/p>\n
\u4ee5\u4e0b\u662f\u4e00\u4e9b\u793a\u4f8b\u6ce8\u89e3\uff1a<\/p>\n
    \n
  1. @Api\uff1a\u7528\u4e8e\u6dfb\u52a0API\u7684\u63cf\u8ff0\u4fe1\u606f<\/li>\n<\/ol>\n
    @Api(value=\"User\",tags={\"User \u64cd\u4f5c\u63a5\u53e3\"})\n@Controller\n@RequestMapping(\"\/users\")\npublic class UserController {\n    \/\/ ...\n}<\/pre>\n
      \u767b\u5f55\u540e\u590d\u5236   <\/p>\n
      \n
    1. @ApiOperation\uff1a\u7528\u4e8e\u6dfb\u52a0API\u64cd\u4f5c\u7684\u63cf\u8ff0\u4fe1\u606f<\/li>\n<\/ol>\n
      @ApiOperation(value = \"\u83b7\u53d6\u7528\u6237\u5217\u8868\", notes = \"\")\n@GetMapping(value = \"\/list\")\npublic Result getUserList() {\n    List<user> userList = userService.listUser();\n    return Result.success(userList);\n}<\/user><\/pre>\n
        \u767b\u5f55\u540e\u590d\u5236   <\/p>\n
        \n
      1. @ApiParam\uff1a\u7528\u4e8e\u6dfb\u52a0API\u64cd\u4f5c\u53c2\u6570\u7684\u63cf\u8ff0\u4fe1\u606f<\/li>\n<\/ol>\n
        @ApiOperation(value = \"\u83b7\u53d6\u7528\u6237\u4fe1\u606f\", notes = \"\u6839\u636eurl\u7684id\u6765\u83b7\u53d6\u7528\u6237\u8be6\u7ec6\u4fe1\u606f\")\n@GetMapping(value = \"\/{id}\")\npublic Result getUserById(@ApiParam(value = \"\u7528\u6237ID\", required = true) @PathVariable Long id) {\n    User user = userService.getUserById(id);\n    return Result.success(user);\n}<\/pre>\n
          \u767b\u5f55\u540e\u590d\u5236   <\/p>\n
        \u6b65\u9aa43\uff1a\u542f\u52a8\u5e94\u7528\u7a0b\u5e8f\u5e76\u8bbf\u95eeSwagger UI<\/p>\n
        \u5728\u5b8c\u6210Swagger\u6ce8\u89e3\u7f16\u5199\u540e\uff0c\u4f7f\u7528\u6d4f\u89c8\u5668\u6253\u5f00Swagger UI\u7684\u5730\u5740\u3002\u5b83\u4f1a\u6839\u636e\u60a8\u7684API\u81ea\u52a8\u6784\u5efa\u53ef\u89c6\u5316API\u6587\u6863\u3002<\/p>\n
        Swagger UI\u7684\u9ed8\u8ba4\u5730\u5740\u4e3a\uff1ahttp:\/\/localhost:8080\/swagger-ui.html<\/p>\n
        \u5728Swagger UI\u754c\u9762\u4e0a\uff0c\u53ef\u4ee5\u770b\u5230API\u7684\u4e00\u4efd\u6982\u8ff0\u3001\u5404\u79cdAPI\u63a5\u53e3\u7684\u63cf\u8ff0\u3001\u8bf7\u6c42\u548c\u54cd\u5e94\u53c2\u6570\u4ee5\u53ca\u4e00\u4e9b\u6d4b\u8bd5\u4ee3\u7801\u7b49\u3002\u8fd9\u53ef\u4ee5\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u66f4\u597d\u7684\u7406\u89e3\u548c\u4f7f\u7528API\u3002 <\/p>\n
        \u603b\u7ed3<\/p>\n
        Swagger\u662f\u4e00\u4e2a\u5f3a\u5927\u7684API\u6587\u6863\u5de5\u5177\uff0c\u53ef\u4ee5\u81ea\u52a8\u751f\u6210\u6613\u4e8e\u9605\u8bfb\u548c\u4ea4\u4e92\u7684API\u6587\u6863\u3002\u4f7f\u7528Swagger\u80fd\u591f\u63d0\u9ad8API\u5f00\u53d1\u7684\u6548\u7387\u548c\u8d28\u91cf, \u5e76\u51cf\u5c11\u624b\u52a8\u7f16\u5199API\u6587\u6863\u6240\u9700\u7684\u65f6\u95f4\u548c\u8d44\u6e90\u3002\u901a\u8fc7\u9075\u5faa\u4e0a\u8ff0\u6b65\u9aa4\uff0c\u60a8\u53ef\u4ee5\u8f7b\u677e\u5730\u5f00\u59cb\u4f7f\u7528Swagger\u6765\u81ea\u52a8\u751f\u6210API\u6587\u6863\u3002<\/p>\n
        \u4ee5\u4e0a\u5c31\u662f\u600e\u6837\u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\uff1f\u7684\u8be6\u7ec6\u5185\u5bb9\uff0c\u66f4\u591a\u8bf7\u5173\u6ce8\u7c73\u4e91\u5176\u5b83\u76f8\u5173\u6587\u7ae0\uff01<\/p>\n","protected":false},"excerpt":{"rendered":"
        \u968f\u7740web\u5e94\u7528\u7a0b\u5e8f\u7684\u5feb\u901f\u53d1\u5c55\uff0capi\u6587\u6863\u8d8a\u6765\u8d8a\u91cd\u8981\u3002api\u6587\u6863\u65e8\u5728\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u7406\u89e3api\u7684\u4f7f\u7528\u65b9\u6cd5\u548c\u53c2\u6570\uff0c\u51cf\u5c11\u65f6\u95f4\u548c\u8d44\u6e90\u6d6a\u8d39\u3002\u7136\u800c\uff0c\u624b\u52a8\u7f16\u5199api\u6587\u6863\u53ef\u80fd\u4f1a\u5f88\u9ebb\u70e6\u4e14\u8d39\u65f6\uff0c\u8fd9\u65f6\u5019swagger\u5219\u6210\u4e3a\u4e86\u5f00\u53d1\u4eba\u5458\u7684\u5229\u5668\u3002swagger\u662f\u4e00\u79cd\u6d41\u884c\u7684api\u6587\u6863\u5de5\u5177\uff0c\u53ef\u4ee5\u81ea\u52a8\u5316\u751f\u6210\u53ef\u8bfb\u6027\u5f3a\uff0c\u4ea4\u4e92\u6027\u7684api\u6587\u6863\u3002\u5728\u672c\u6587\u4e2d\uff0c\u6211\u4eec\u4ecb\u7ecd\u4e86\u5982\u4f55\u4f7f\u7528swagger\u6765\u81ea\u52a8\u751f\u6210api\u6587\u6863\u3002 \u4ec0\u4e48\u662fSwagger\uff1f Swagger\u662f\u4e00\u7ec4\u5f00\u6e90\u5de5\u5177\uff0c\u53ef\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u6784\u5efa\uff0c\u8bbe\u8ba1\uff0c\u63cf\u8ff0\u548c\u4f7f\u7528RESTful Web\u670d\u52a1\u3002 Swagger\u5141\u8bb8\u60a8\u4f7f\u7528\u7528\u4e8e\u63cf\u8ff0API\u64cd\u4f5c\u7684YAML\u6216JSON\u683c\u5f0f\u7f16\u5199API\u6587\u6863\uff0c\u5e76\u751f\u6210\u6613\u4e8e\u9605\u8bfb\u548c\u4ea4\u4e92\u7684\u63a5\u53e3\u6587\u6863\u3002 Swagger\u652f\u6301\u591a\u79cd\u7f16\u7a0b\u8bed\u8a00\u548c\u6846\u67b6\uff0c\u4f8b\u5982Java\uff0cC\uff03\uff0cPython\u548cRuby\u3002\u5b83\u8fd8\u53ef\u4ee5\u4e0e\u8bb8\u591a\u73b0\u6709\u7684API\u6846\u67b6\u8fdb\u884c\u96c6\u6210\uff0c\u5305\u62ecSpring\uff0cExpress\u548cDjango\u7b49\u3002 \u4f7f\u7528Swagger\u751f\u6210API\u6587\u6863\u9700\u8981\u5148\u5b89\u88c5Swagger UI\u3002Swagger UI\u662f\u4e00\u4e2a\u4ea4\u4e92\u5f0fAPI\u6587\u6863\u7f51\u7ad9\uff0c\u72ec\u7acb\u4e8eAPI\uff0c\u5e76\u8ddf\u968fSwagger\u89c4\u8303\u3002\u5b83\u63d0\u4f9b\u4e86API\u6587\u6863\u53ef\u89c6\u5316\u7684\u6f02\u4eae\u754c\u9762\uff0c\u5e76\u652f\u6301\u81ea\u52a8\u5316\u5c1d\u8bd5API\u8c03\u7528\u3002 \u6b65\u9aa41\uff1a\u914d\u7f6eSwagger \u8981\u4f7f\u7528Swagger\uff0c\u9700\u8981\u5148\u4e0b\u8f7dSwagger\u5305\uff0c\u53ef\u4ee5\u4eceSwagger\u7f51\u7ad9\u83b7\u53d6\u6216\u4f7f\u7528\u4f9d\u8d56\u7ba1\u7406\u5668\u8fdb\u884c\u4e0b\u8f7d\u3002 \u5728Java Spring Boot\u9879\u76ee\u4e2d\u914d\u7f6eSwagger API\uff0c\u9700\u8981\u5728maven\u4f9d\u8d56\u4e2d\u6dfb\u52a0\u4ee5\u4e0bSwagger\u4f9d\u8d56\uff1a <dependency><groupid>io.springfox<\/groupid><artifactid>springfox-swagger2<\/artifactid><version>${springfox-swagger2.version}<\/version><\/dependency><dependency><groupid>io.springfox<\/groupid><artifactid>springfox-swagger-ui<\/artifactid><version>${springfox-swagger-ui.version}<\/version><\/dependency> \u767b\u5f55\u540e\u590d\u5236 \u5176\u4e2d${springfox-swagger2.version}\u548c${springfox-swagger-ui.version}\u4ee3\u8868Swagger\u7248\u672c\u53f7\u3002 \u914d\u7f6e\u6587\u4ef6application.properties\u4e2d\u5f00\u542fswagger\uff1a #\u5f00\u542fswagger swagger.enabled = true \u767b\u5f55\u540e\u590d\u5236 \u6b65\u9aa42\uff1a\u7f16\u5199Swagger\u6ce8\u89e3 Swagger\u4f7f\u7528\u6ce8\u89e3\u6765\u63cf\u8ff0API\u4e2d\u7684\u64cd\u4f5c\u548c\u53c2\u6570\u3002\u5728API\u63a7\u5236\u5668\u7c7b\u548c\u5176\u65b9\u6cd5\u7684\u9876\u90e8\u6dfb\u52a0Swagger\u6ce8\u89e3\uff0c\u4ee5\u4fbfSwagger\u80fd\u591f\u6b63\u786e\u5730\u89e3\u6790\u548c\u751f\u6210\u6587\u6863\u5e76\u5728Swagger UI\u4e0a\u663e\u793a\u3002 \u4ee5\u4e0b\u662f\u4e00\u4e9b\u793a\u4f8b\u6ce8\u89e3\uff1a @Api\uff1a\u7528\u4e8e\u6dfb\u52a0API\u7684\u63cf\u8ff0\u4fe1\u606f @Api(value=”User”,tags={“User \u64cd\u4f5c\u63a5\u53e3”}) @Controller @RequestMapping(“\/users”) public class UserController { \/\/ … } \u767b\u5f55\u540e\u590d\u5236 @ApiOperation\uff1a\u7528\u4e8e\u6dfb\u52a0API\u64cd\u4f5c\u7684\u63cf\u8ff0\u4fe1\u606f @ApiOperation(value = “\u83b7\u53d6\u7528\u6237\u5217\u8868”, notes = “”) @GetMapping(value = “\/list”) public Result getUserList() { […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[16],"tags":[],"class_list":["post-23253","post","type-post","status-publish","format-standard","hentry","category-16"],"_links":{"self":[{"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/posts\/23253","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/comments?post=23253"}],"version-history":[{"count":0,"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/posts\/23253\/revisions"}],"wp:attachment":[{"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/media?parent=23253"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/categories?post=23253"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/fwq.ai\/blog\/wp-json\/wp\/v2\/tags?post=23253"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}