{"id":2452,"date":"2021-10-08T03:25:46","date_gmt":"2021-10-07T19:25:46","guid":{"rendered":"https:\/\/www.develop-note.com\/blog\/?p=2452"},"modified":"2022-02-16T17:23:16","modified_gmt":"2022-02-16T09:23:16","slug":"swashbuckle","status":"publish","type":"post","link":"https:\/\/www.develop-note.com\/blog\/2021\/10\/08\/swashbuckle\/","title":{"rendered":"D-07-Api\u6587\u4ef6 ? Swashbuckle"},"content":{"rendered":"<h1>Api\u6587\u4ef6<\/h1>\n<p>\u5927\u5bb6\u662f\u4e0d\u662f\u5728\u958b\u767c\u6642\u9084\u8981\u60f3\u8457\u8981\u5982\u4f55\u63d0\u4f9b\u6280\u8853\u6587\u4ef6\uff0c\u5c24\u5176\u662f\u5728\u5fd9\u8457\u958b\u767cApi\u9084\u6c92\u6709\u9918\u529b\u6642\u9084\u8981\u4e00\u908a\u64b0\u5beb\u6587\u4ef6\uff0c\u4e0d\u904e\u9019\u4e9b\u90fd\u9084\u597d\uff0c\u6700\u9ebb\u7169\u7684\u6642\u7576Api\u66f4\u65b0\u6642\u6587\u4ef6\u6c92\u66f4\u65b0\u66f4\u8b93\u4eba\u982d\u75db\uff0c\u6240\u4ee5\u4eca\u5929\u8ddf\u5927\u5bb6\u5206\u4eab\u4e00\u4e0b\u5982\u4f55\u81ea\u52d5\u7522\u751fApi\u6587\u4ef6\u3002<\/p>\n<p><!--more--><\/p>\n<h2>Swashbuckle<\/h2>\n<p>\u300c\u524d\u8f29\uff0c\u4e3b\u7ba1\u8981\u6211\u5011\u63d0\u4f9bApi\u7684\u6280\u8853\u6587\u4ef6\u7d66\u5ee0\u5546\uff0c\u4f60\u6709\u6c92\u6709\u5beb\u904e\u554a\u3002\u300d<br \/>\n\u4eca\u5929\u5927\u982d\u56e0\u70ba\u4e3b\u7ba1\u8ddf\u5ee0\u5546\u958b\u6703\u6642\u5ee0\u5546\u6709\u63d0\u5230\u8aaa\u6c92\u6709Api\u6587\u4ef6\u4e0d\u77e5\u9053\u600e\u9ebc\u958b\u767c\uff0c\u9019\u6642\u5927\u982d\u5c31\u8ddf\u8001K\u8acb\u6559\u8aaa\u8a72\u5982\u4f55\u5bebApi\u6587\u4ef6\u3002<br \/>\n\u300c\u4f60\u5728\u5bebApi\u6642\u6709\u6c92\u6709\u5beb\u8a3b\u89e3\u963f\u3002\u300d<br \/>\n\u807d\u5230\u5927\u982d\u7684\u554f\u984c\u5f8c\u8001K\u8ddf\u554f\u4e86\u9019\u4ef6\u4e8b\uff0c\u7531\u65bc\u554f\u7684\u554f\u984c\u8ddf\u56de\u7b54\u7684\u5167\u5bb9\u4f3c\u4e4e\u6c92\u6709\u95dc\u4fc2\u6240\u4ee5\u5927\u982d\u4e00\u81c9\u7591\u60d1\u7684\u6a23\u5b50\uff0c\u9019\u6642\u5c0f\u5149\u8d70\u904e\u4f86\u3002<br \/>\n\u300c\u524d\u8f29\uff0c\u5927\u982d\u524d\u5099\u6709\u4ea4\u4ee3\u8981\u8a18\u5f97\u518dApi\u7684Action\u8981\u5beb\u8a3b\u89e3\u3002\u300d<br \/>\n\u807d\u5230\u5c0f\u5149\u7684\u56de\u7b54\u5f8c\u8001K\u9ede\u9ede\u982d\uff0c\u4e0d\u904e\u5927\u982d\u66f4\u7591\u60d1\u4e86\u3002<br \/>\n\u300c\u4e0d\u904e\u524d\u8f29\u6211\u5011\u600e\u9ebc\u628a\u8a3b\u89e3\u63d0\u4f9b\u7d66\u5ee0\u5546\u963f\u3002\u300d<br \/>\n\u9019\u6642\u5927\u982d\u8010\u4e0d\u4f4f\u6027\u5b50\u5c31\u628a\u4ed6\u7684\u554f\u984c\u554f\u4e86\u51fa\u4f86\u3002<br \/>\n\u300c\u90a3\u4f60\u8ddf\u5c0f\u5149\u53bb\u7814\u7a76Swashbuckle.AspNetCore\u5427\uff0c\u4ed6\u4e8b\u53ef\u4ee5\u5e6b\u4f60\u7522\u751fApi\u6587\u4ef6\u7684\u5957\u4ef6\uff0c\u4f60\u770b\u4e00\u770b\u5427\u9019\u6a23\u5c31\u4e0d\u7528\u53e6\u5916\u82b1\u6642\u9593\u5beb\u6587\u4ef6\u4e86\u3002\u300d<br \/>\n\u6240\u4ee5\u5c0f\u5149\u5c31\u8ddf\u5927\u982d\u958b\u59cb\u7814\u7a76<a href=\"https:\/\/github.com\/domaindrivendev\/Swashbuckle.AspNetCore\" title=\"Swashbuckle\" rel=\"nofollow noopener\" target=\"_blank\">Swashbuckle<\/a>\u3002<\/p>\n<h3>\u74b0\u5883\u8a2d\u5b9a<\/h3>\n<p>\u4e00\u5982\u5f80\u6614\u7684\u6211\u5011\u5148\u5b89\u88dd\u6240\u9700\u7684\u5957\u4ef6\uff0c\u9019\u6642\u4e00\u6a23\u8f38\u5165\u4ee5\u4e0b\u6307\u4ee4\u5373\u53ef\u3002<\/p>\n<pre><code class=\"language-bash\">dotnet add package Swashbuckle.AspNetCore<\/code><\/pre>\n<p>\u5982\u6b64\u4ed6\u6703\u4e00\u4f75\u5b89\u88dd\u4ee5\u4e0b\u76f8\u4f9d\u7684\u5957\u4ef6\uff0c\u6240\u4ee5\u53ef\u4ee5\u4e0d\u7528\u7279\u5225\u53bb\u5b89\u88dd\u4ed6\u3002<\/p>\n<ul>\n<li>Swashbuckle.AspNetCore.Swagger<\/li>\n<li>Swashbuckle.AspNetCore.SwaggerGen<\/li>\n<li>Swashbuckle.AspNetCore.SwaggerUI<\/li>\n<\/ul>\n<p>\u5b89\u88dd\u5b8c\u6210\u4e4b\u5f8c\u958b\u59cb\u8981\u8a2d\u5b9a\u4f7f\u7528Swashbuckle\u5728\u6211\u5011\u7684\u5c08\u6848\u5167\u4e86\u3002<\/p>\n<h3>\u8a2d\u5b9aApi\u6587\u4ef6<\/h3>\n<p>\u9996\u5148\u6211\u5011\u5148\u8a2d\u5b9a\u8b93\u6211\u5011\u7684dotnetcore\u53ef\u4ee5\u4f7f\u7528Swashbuckle\u7684\u529f\u80fd\uff0c\u9996\u5148\u5728<code>Startup.ConfigureServices<\/code>\u52a0\u5165\u4ee5\u4e0b\u5167\u5bb9\u3002<\/p>\n<pre><code class=\"language-cs\">services.AddSwaggerGen(c =&gt;\n{\n    c.SwaggerDoc(&quot;\u7248\u865f&quot;, new OpenApiInfo { Title = &quot;\u5c08\u6848\u540d\u7a31&quot;, Version = &quot;\u7248\u865f&quot; });\n});<\/code><\/pre>\n<p>\u518d\u4f86\u662f\u5728\u518d<code>Startup.Configure<\/code>\u52a0\u5165\u4ee5\u4e0b\u5167\u5bb9\u8a2d\u5b9amiddleware<\/p>\n<pre><code class=\"language-cs\">app.UseSwagger();\napp.UseSwaggerUI(c =&gt; c.SwaggerEndpoint(&quot;\/swagger\/\u7248\u865f\/swagger.json&quot;, &quot;\u5c08\u6848\u540d\u7a31 \u7248\u865f&quot;));<\/code><\/pre>\n<p>\u8a2d\u5b9a\u5b8c\u5f8c\u57f7\u884c\u5c08\u6848\u9032\u5165\u5230<code>root\/swagger\/index.html<\/code>\u5c31\u53ef\u4ee5\u770b\u5230\u9810\u8a2d\u7684Swagger\u7684\u756b\u9762\u4e86\uff0c\u4e0d\u904e\u76f8\u4fe1\u5927\u5bb6\u9019\u6642\u61c9\u8a72\u9084\u6c92\u6709\u770b\u5230\u8aaa\u660e\u5167\u5bb9\u3002<\/p>\n<p><a href=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_no_xml.png\"><img decoding=\"async\" src=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_no_xml.png\" alt=\"Swagger\u6c92\u6709\u8aaa\u660e\u6587\u5b57\" \/> Swagger\u6c92\u6709\u8aaa\u660e\u6587\u5b57<\/a><\/p>\n<h3>\u52a0\u5165\u8aaa\u660e\u6587\u4ef6<\/h3>\n<p>\u9019\u90e8\u5206\u8981\u8b93\u6211\u5011\u7684Swagger\u5167\u6709\u8aaa\u660e\u5167\u5bb9\uff0c\u4e0d\u904e\u5728\u9019\u4e4b\u524d\u5148\u8ddf\u5927\u5bb6\u4ecb\u7d39\u5982\u4f55\u7522\u751f\u8aaa\u660e\u6587\u4ef6\uff0c\u9996\u5148\u5728\u6211\u5011\u7684\u7a0b\u5f0f\u78bc\u4e2d\u8981\u6709<code>summary<\/code>\u7684\u6a19\u7c64\uff0c\u5982\u4e0b\u6240\u793a\u3002<\/p>\n<pre><code class=\"language-cs\">\/\/\/ &lt;summary&gt;\n\/\/\/ \u53d6\u5f97\u6eab\u5ea6\n\/\/\/ &lt;\/summary&gt;\n\/\/\/ &lt;returns&gt;\u6eab\u5ea6\u7684\u5217\u8209&lt;\/returns&gt;\n[HttpGet]\npublic IEnumerable&lt;WeatherForecast&gt; Get()\n.\n.\n.\n\/\/\/ &lt;summary&gt;\n\/\/\/ \u4f9d\u64da\u5730\u5340\u53d6\u6eab\u5ea6\n\/\/\/ &lt;\/summary&gt;\n\/\/\/ &lt;param name=&quot;zoneId&quot;&gt;\u5730\u5340\u7de8\u865f&lt;\/param&gt;\n\/\/\/ &lt;returns&gt;\u6eab\u5ea6\u5217\u8209&lt;\/returns&gt;\n[HttpGet(&quot;ByZone&quot;)]\npublic IEnumerable&lt;WeatherForecast&gt; GetByZone(string zoneId)<\/code><\/pre>\n<p>\u6709\u4e86\u8aaa\u660e\u8cc7\u8a0a\u4e4b\u5f8c\u9810\u8a2d\u7684vscode\u4e8b\u4e0d\u6703\u7522\u51faxml\u6a94\u6848\uff0c\u6240\u4ee5\u6211\u5011\u8981\u70ba\u5c08\u6848\u6a94<code>.csproj<\/code>\u505a\u4ee5\u4e0b\u7684\u4fee\u6539\u3002<\/p>\n<pre><code>  &lt;PropertyGroup&gt;\n    &lt;TargetFramework&gt;net5.0&lt;\/TargetFramework&gt;\n    &lt;GenerateDocumentationFile&gt;true&lt;\/GenerateDocumentationFile&gt;\n    &lt;NoWarn&gt;1701;1702;1705;1591&lt;\/NoWarn&gt;\n  &lt;\/PropertyGroup&gt;<\/code><\/pre>\n<p>\u7c21\u55ae\u8aaa\u660e\u5728<code>PropertyGroup<\/code>\u88e1\u9762\u7684<code>TargetFramework<\/code>\u4e0b\u9762\u5bb6\u5169\u500b\u9805\u76ee\u5373\u53ef\u3002\u5982\u6b64\u5728<code>bin<\/code>\u8cc7\u6599\u593e\u4e0b\u61c9\u8a72\u53ef\u4ee5\u770b\u5230<code>\u5c08\u6848\u540d\u7a31.xml<\/code>\u9019\u500b\u6587\u4ef6\u6a94\u3002\u5728\u53ef\u4ee5\u7522\u51fa\u6587\u4ef6\u7576\u5f8c\u6211\u5011\u8981\u8a2d\u5b9aSwagger\u4f86\u8b80\u53d6\u6211\u5011\u7684\u6587\u4ef6\u6a94\u505a\u70baApi\u7684\u6587\u4ef6\uff0c\u9019\u90e8\u5206\u5728<code>services.AddSwaggerGen<\/code>\u52a0\u5165\u4ee5\u4e0b\u5167\u5bb9\u5373\u53ef\u3002<\/p>\n<pre><code class=\"language-cs\">\/\/ Set the comments path for the Swagger JSON and UI.\nvar xmlFile = $&quot;{Assembly.GetExecutingAssembly().GetName().Name}.xml&quot;;\nvar xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\nc.IncludeXmlComments(xmlPath);<\/code><\/pre>\n<p>\u52a0\u5165\u4e4b\u5f8c\u5728\u756b\u9762\u4e0a\u61c9\u8a72\u53ef\u4ee5\u770b\u5230\u8aaa\u660e\u5167\u5bb9\u3002<\/p>\n<p><a href=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_with_xml.png\"><img decoding=\"async\" src=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_with_xml.png\" alt=\"Swagger\u6709\u8aaa\u660e\u6587\u5b57\" \/> Swagger\u6709\u8aaa\u660e\u6587\u5b57<\/a><\/p>\n<h3>\u8207jwt\u7684\u5354\u4f5c<\/h3>\n<p>\u4e4b\u524d\u6709\u904ejwt\u7684api\u5728swagger\u8a72\u5982\u4f55\u8655\u7406\u5462\uff0c\u6240\u4ee5\u9019\u908a\u8aaa\u660e\u4e00\u4e0b\u5982\u4f55\u4f7f\u7528swagger\u8ddfjwt\u4f86\u5354\u4f5c\uff0c\u9996\u5148\u5148\u5728<code>services.AddSwaggerGen<\/code>\u52a0\u5165\u4ee5\u4e0b\u5167\u5bb9\u3002<\/p>\n<pre><code class=\"language-cs\">c.AddSecurityDefinition(&quot;Bearer&quot;,\n    new OpenApiSecurityScheme\n    {\n        In = ParameterLocation.Header,\n        Description = &quot;Please insert JWT with Bearer into field&quot;,\n        Name = &quot;Authorization&quot;,\n        Type = SecuritySchemeType.ApiKey\n    });\n\nc.AddSecurityRequirement(new OpenApiSecurityRequirement\n{\n    {\n        new OpenApiSecurityScheme\n        {\n            Reference = new OpenApiReference\n            {\n                Type = ReferenceType.SecurityScheme,\n                Id = &quot;Bearer&quot;\n            }\n        },\n        new string[] { }\n    }\n});<\/code><\/pre>\n<p>\u76f8\u4fe1\u52a0\u5165\u4e4b\u5f8c\u53ef\u4ee5\u770b\u5230\u4ee5\u4e0b\u756b\u9762\u3002<\/p>\n<p><a href=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_with_jwt.png\"><img decoding=\"async\" src=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_with_jwt.png\" alt=\"Swagger\u5305\u542bJWT\" \/> Swagger\u5305\u542bJWT<\/a><\/p>\n<p>\u7576\u9ede\u64ca<code>Authorize<\/code>\u6703\u51fa\u73fe\u4ee5\u4e0b\u5167\u5bb9\u3002<br \/>\n<a href=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_jwt.png\"><img decoding=\"async\" src=\"https:\/\/www.develop-note.com\/blog\/wp-content\/uploads\/2021\/10\/2021ironman_swagger_jwt.png\" alt=\"Swagger\u7684Token\u8f38\u5165\" \/> Swagger\u7684Token\u8f38\u5165<\/a><\/p>\n<p>\u6700\u5f8c\u8a18\u5f97\u8f38\u5165\u7684\u5167\u5bb9\u8981\u662f<code>Bearer  (apiKey)<\/code>\u7684\u683c\u5f0f\u3002<\/p>\n<h2>\u5f8c\u8a18<\/h2>\n<p>\u4eca\u5929\u8ddf\u5927\u5bb6\u4ecb\u7d39\u5982\u4f55\u5728Api\u5167\u52a0\u5165<a href=\"https:\/\/en.wikipedia.org\/wiki\/OpenAPI_Specification\" title=\"OpenAPI\" rel=\"nofollow noopener\" target=\"_blank\">OpenAPI<\/a>\u7684\u8aaa\u660e\u6587\u4ef6\uff0c\u800c\u4e14Api\u66f4\u65b0\u4e4b\u5f8c\u6587\u4ef6\u4e5f\u6703\u96a8\u8457\u8ddf\u65b0\uff0c\u518d\u4f86\u9084\u6709\u6e2c\u8a66\u63a5\u53e3\u4e0d\u7528\u518d\u7279\u5225\u900f\u904e<a href=\"https:\/\/www.postman.com\/\" title=\"POSTMAN\" rel=\"nofollow noopener\" target=\"_blank\">POSTMAN<\/a>\uff0c\u5e0c\u671b\u70ba\u5927\u5bb6\u958b\u767c\u6642\u6709\u5e6b\u52a9\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Api\u6587\u4ef6 \u5927\u5bb6\u662f\u4e0d\u662f\u5728\u958b\u767c\u6642\u9084\u8981\u60f3\u8457\u8981\u5982\u4f55\u63d0\u4f9b\u6280\u8853\u6587\u4ef6\uff0c\u5c24\u5176\u662f\u5728\u5fd9\u8457\u958b\u767cApi\u9084\u6c92\u6709\u9918\u529b\u6642\u9084\u8981\u4e00\u908a\u64b0\u5beb\u6587\u4ef6\uff0c &hellip; <\/p>\n<p class=\"link-more\"><a href=\"https:\/\/www.develop-note.com\/blog\/2021\/10\/08\/swashbuckle\/\" class=\"more-link\">\u95b1\u8b80\u5168\u6587<span class=\"screen-reader-text\">\u3008D-07-Api\u6587\u4ef6 ? Swashbuckle\u3009<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"_exactmetrics_skip_tracking":false,"_exactmetrics_sitenote_active":false,"_exactmetrics_sitenote_note":"","_exactmetrics_sitenote_category":0,"footnotes":""},"categories":[2],"tags":[90,92,142],"class_list":["post-2452","post","type-post","status-publish","format-standard","hentry","category-develop","tag-2021ironman","tag-dotnetcore","tag-swashbuckle"],"_links":{"self":[{"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/posts\/2452","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/comments?post=2452"}],"version-history":[{"count":20,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/posts\/2452\/revisions"}],"predecessor-version":[{"id":2927,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/posts\/2452\/revisions\/2927"}],"wp:attachment":[{"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/media?parent=2452"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/categories?post=2452"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.develop-note.com\/blog\/wp-json\/wp\/v2\/tags?post=2452"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}