https:\/\/localhost:5001\/swagger\/index.html<\/a>:<\/p>\n![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3001.jpg\")
<\/p>\n
Also if we expand the Schemas part, we are going to find the DTOs that we used in our project.
\n\u6b64\u5916\uff0c\u5982\u679c\u6211\u4eec\u6269\u5c55 Schemas \u90e8\u5206\uff0c\u6211\u4eec\u5c06\u627e\u5230\u6211\u4eec\u5728\u9879\u76ee\u4e2d\u4f7f\u7528\u7684 DTO\u3002<\/p>\n
If we click on a specific controller to expand its details, we are going to see all the actions inside:
\n\u5982\u679c\u6211\u4eec\u5355\u51fb\u7279\u5b9a\u63a7\u5236\u5668\u4ee5\u5c55\u5f00\u5176\u8be6\u7ec6\u4fe1\u606f\uff0c\u6211\u4eec\u5c06\u770b\u5230\u5176\u4e2d\u7684\u6240\u6709\u4f5c\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3002.jpg\")
<\/p>\n
Once we click on an action method, we can see detailed information like parameters, response, and example values. There is also an option to try out each of those action methods by clicking the Try it out button.
\n\u5355\u51fb\u4f5c\u65b9\u6cd5\u540e\uff0c\u6211\u4eec\u53ef\u4ee5\u770b\u5230\u53c2\u6570\u3001\u54cd\u5e94\u548c\u793a\u4f8b\u503c\u7b49\u8be6\u7ec6\u4fe1\u606f\u3002\u8fd8\u6709\u4e00\u4e2a\u9009\u9879\uff0c\u53ef\u4ee5\u901a\u8fc7\u5355\u51fb Try it out \uff08\u8bd5\u7528\uff09 \u6309\u94ae\u6765\u5c1d\u8bd5\u8fd9\u4e9b\u4f5c\u65b9\u6cd5\u4e2d\u7684\u6bcf\u4e00\u79cd\u3002<\/p>\n
So, let\u2019s try it with the \/api\/companies action:
\n\u90a3\u4e48\uff0c\u8ba9\u6211\u4eec\u7528 \/api\/companies\u4f5c\u6765\u8bd5\u8bd5\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3003.jpg\")
<\/p>\n
Once we click the Execute button, we are going to see that we get our response:
\n\u5355\u51fb Execute \u6309\u94ae\u540e\uff0c\u6211\u4eec\u5c06\u770b\u5230\u6211\u4eec\u6536\u5230\u4e86\u54cd\u5e94\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3004.jpg\")
<\/p>\n
And this is an expected response. We are not authorized. To enable authorization, we have to add some modifications.
\n\u8fd9\u662f\u610f\u6599\u4e4b\u4e2d\u7684\u56de\u5e94\u3002\u6211\u4eec\u6ca1\u6709\u83b7\u5f97\u6388\u6743\u3002\u8981\u542f\u7528\u6388\u6743\uff0c\u6211\u4eec\u5fc5\u987b\u6dfb\u52a0\u4e00\u4e9b\u4fee\u6539\u3002<\/p>\n
30.3 Adding Authorization Support<\/h2>\n
30.3 \u6dfb\u52a0\u6388\u6743\u652f\u6301<\/p>\n
To add authorization support, we need to modify the ConfigureSwagger\u200c method:
\n\u8981\u6dfb\u52a0\u6388\u6743\u652f\u6301\uff0c\u6211\u4eec\u9700\u8981\u4fee\u6539 ConfigureSwagger \u65b9\u6cd5\uff1a<\/p>\n
public static void ConfigureSwagger(this IServiceCollection services) { services.AddSwaggerGen(s => { s.SwaggerDoc("v1", new OpenApiInfo { Title = "Code Maze API", Version = "v1" }); s.SwaggerDoc("v2", new OpenApiInfo { Title = "Code Maze API", Version = "v2" }); s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { In = ParameterLocation.Header, Description = "Place to add JWT with Bearer", Name = "Authorization", Type = SecuritySchemeType.ApiKey, Scheme = "Bearer" }); s.AddSecurityRequirement(new OpenApiSecurityRequirement() { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer"}, Name = "Bearer", }, new List<string>() } }); }); }\n<\/code><\/pre>\nWith this modification, we are adding the security definition in our swagger configuration. Now, we can start our app again and navigate to the index.html page.
\n\u901a\u8fc7\u6b64\u4fee\u6539\uff0c\u6211\u4eec\u5c06\u5728 swagger \u914d\u7f6e\u4e2d\u6dfb\u52a0\u5b89\u5168\u5b9a\u4e49\u3002\u73b0\u5728\uff0c\u6211\u4eec\u53ef\u4ee5\u518d\u6b21\u542f\u52a8\u6211\u4eec\u7684\u5e94\u7528\u7a0b\u5e8f\u5e76\u5bfc\u822a\u5230 index.html \u9875\u9762\u3002<\/p>\n
The first thing we are going to notice is the Authorize options for requests:
\n\u6211\u4eec\u9996\u5148\u8981\u6ce8\u610f\u7684\u662f\u8bf7\u6c42\u7684 Authorize \u9009\u9879\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3005.jpg\")
<\/p>\n
We are going to use that in a moment. But let\u2019s get our token first. For that, let\u2019s open the api\/authentication\/login action, click try it out, add credentials, and copy the received token:
\n\u6211\u4eec\u7a0d\u540e\u4f1a\u7528\u5230\u5b83\u3002\u4f46\u662f\uff0c\u8ba9\u6211\u4eec\u5148\u83b7\u53d6\u6211\u4eec\u7684\u4ee4\u724c\u3002\u4e3a\u6b64\uff0c\u8ba9\u6211\u4eec\u6253\u5f00 api\/authentication\/login\u4f5c\uff0c\u5355\u51fb try it out\uff0c\u6dfb\u52a0\u51ed\u636e\uff0c\u7136\u540e\u590d\u5236\u6536\u5230\u7684\u4ee4\u724c\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3006.png\")
<\/p>\n
Once we have copied the token, we are going to click on the authorization button for the \/api\/companies request, paste it with the Bearer in front of it, and click Authorize:
\n\u590d\u5236\u4ee4\u724c\u540e\uff0c\u6211\u4eec\u5c06\u5355\u51fb \/api\/companies \u8bf7\u6c42\u7684\u6388\u6743\u6309\u94ae\uff0c\u5c06\u5176\u7c98\u8d34\u5230\u5176\u524d\u9762\u5e76\u5e26\u6709 Bearer\uff0c\u7136\u540e\u5355\u51fb Authorize\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3007.jpg\")
<\/p>\n
After authorization, we are going to click on the Close button and try our request:
\n\u6388\u6743\u540e\uff0c\u6211\u4eec\u5c06\u5355\u51fb Close \u6309\u94ae\u5e76\u5c1d\u8bd5\u6211\u4eec\u7684\u8bf7\u6c42\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3008.jpg\")
<\/p>\n
And we get our response. Excellent job.
\n\u6211\u4eec\u5f97\u5230\u4e86\u6211\u4eec\u7684\u56de\u5e94\u3002\u5e72\u5f97\u597d\u3002<\/p>\n
\u300030.4 Extending Swagger Configuration<\/h2>\n
30.4 \u6269\u5c55 Swagger \u914d\u7f6e<\/p>\n
Swagger provides options for extending the documentation and customizing the UI. Let\u2019s explore some of those.\u200c
\nSwagger \u63d0\u4f9b\u4e86\u7528\u4e8e\u6269\u5c55\u6587\u6863\u548c\u81ea\u5b9a\u4e49 UI \u7684\u9009\u9879\u3002\u8ba9\u6211\u4eec\u6765\u63a2\u8ba8\u5176\u4e2d\u7684\u4e00\u4e9b\u3002<\/p>\n
First, let\u2019s see how we can specify the API info and description. The configuration action passed to the AddSwaggerGen() method adds information such as Contact, License, and Description. Let\u2019s provide some values for those:
\n\u9996\u5148\uff0c\u8ba9\u6211\u4eec\u770b\u770b\u5982\u4f55\u6307\u5b9a API \u4fe1\u606f\u548c\u63cf\u8ff0\u3002\u4f20\u9012\u7ed9 AddSwaggerGen\uff08\uff09 \u65b9\u6cd5\u7684\u914d\u7f6e\u4f5c\u5c06\u6dfb\u52a0 Contact\u3001License \u548c Description \u7b49\u4fe1\u606f\u3002\u8ba9\u6211\u4eec\u4e3a\u8fd9\u4e9b\u503c\u63d0\u4f9b\u4e00\u4e9b\u503c\uff1a<\/p>\n
s.SwaggerDoc("v1", new OpenApiInfo { Title = "Code Maze API", Version = "v1", Description = "CompanyEmployees API by CodeMaze", TermsOfService = new Uri("https:\/\/example.com\/terms"), Contact = new OpenApiContact { Name = "John Doe", Email = "John.Doe@gmail.com", Url = new Uri("https:\/\/twitter.com\/johndoe"), }, License = new OpenApiLicense { Name = "CompanyEmployees API LICX", Url = new Uri("https:\/\/example.com\/license"), } });\n......<\/code><\/pre>\nWe have implemented this just for the first version, but you get the point. Now, let\u2019s run the application once again and explore the Swagger UI:
\n\u6211\u4eec\u53ea\u4e3a\u7b2c\u4e00\u4e2a\u7248\u672c\u5b9e\u73b0\u4e86\u8fd9\u4e00\u70b9\uff0c\u4f46\u60a8\u660e\u767d\u4e86\u3002\u73b0\u5728\uff0c\u8ba9\u6211\u4eec\u518d\u6b21\u8fd0\u884c\u5e94\u7528\u7a0b\u5e8f\u5e76\u63a2\u7d22 Swagger UI\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3009.jpg\")
<\/p>\n
For enabling XML comments, we need to suppress warning 1591, which will now give warnings about any method, class, or field that doesn\u2019t have triple-slash comments. We need to do this in the Presentation project.
\n\u8981\u542f\u7528 XML \u6ce8\u91ca\uff0c\u6211\u4eec\u9700\u8981\u7981\u6b62\u663e\u793a\u8b66\u544a 1591\uff0c\u5b83\u73b0\u5728\u5c06\u9488\u5bf9\u4efb\u4f55\u6ca1\u6709\u4e09\u659c\u6760\u6ce8\u91ca\u7684\u65b9\u6cd5\u3001\u7c7b\u6216\u5b57\u6bb5\u53d1\u51fa\u8b66\u544a\u3002\u6211\u4eec\u9700\u8981\u5728 Presentation \u9879\u76ee\u4e2d\u6267\u884c\u6b64\u4f5c\u3002<\/p>\n
Additionally, we have to add the documentation path for the same project, since our controllers are in the Presentation project:
\n\u6b64\u5916\uff0c\u6211\u4eec\u5fc5\u987b\u4e3a\u540c\u4e00\u9879\u76ee\u6dfb\u52a0\u6587\u6863\u8def\u5f84\uff0c\u56e0\u4e3a\u6211\u4eec\u7684\u63a7\u5236\u5668\u4f4d\u4e8e Presentation \u9879\u76ee\u4e2d\uff1a<\/p>\n
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>net6.0<\/TargetFramework> <ImplicitUsings>enable<\/ImplicitUsings> <Nullable>enable<\/Nullable> <\/PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>CompanyEmployees.Presentation.xml<\/DocumentationFile> <OutputPath><\/OutputPath> <NoWarn>1701;1702;1591<\/NoWarn> <\/PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'"> <NoWarn>1701;1702;1591<\/NoWarn> <\/PropertyGroup><\/code><\/pre>\nNow, let\u2019s modify our configuration:
\n\u73b0\u5728\uff0c\u8ba9\u6211\u4eec\u4fee\u6539\u6211\u4eec\u7684\u914d\u7f6e\uff1a<\/p>\n
s.SwaggerDoc("v2", new OpenApiInfo { Title = "Code Maze API", Version = "v2" }); var xmlFile = $"{typeof(Presentation.AssemblyReference).Assembly.GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); s.IncludeXmlComments(xmlPath);<\/code><\/pre>\nNext, adding triple-slash comments to the action method enhances the Swagger UI by adding a description to the section header:
\n\u63a5\u4e0b\u6765\uff0c\u901a\u8fc7\u5411\u90e8\u5206\u6807\u9898\u6dfb\u52a0\u8bf4\u660e\uff0c\u5411\u4f5c\u65b9\u6cd5\u6dfb\u52a0\u4e09\u659c\u6760\u6ce8\u91ca\u53ef\u589e\u5f3a Swagger UI\uff1a<\/p>\n
\/\/\/ <summary> \/\/\/ Gets the list of all companies \/\/\/ <\/summary> \/\/\/ <returns>The companies list<\/returns> [HttpGet(Name = "GetCompanies")] [Authorize(Roles = "Manager")] public async Task<IActionResult> GetCompanies()<\/code><\/pre>\nAnd this is the result:
\n\u7ed3\u679c\u5982\u4e0b\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3010.jpg\")
<\/p>\n
The developers who consume our APIs are usually more interested in what it returns \u2014 specifically the response types and error codes. Hence, it is very important to describe our response types. These are denoted using XML comments and data annotations.
\n\u4f7f\u7528\u6211\u4eec\u7684 API \u7684\u5f00\u53d1\u4eba\u5458\u901a\u5e38\u5bf9\u5b83\u8fd4\u56de\u7684\u5185\u5bb9\u66f4\u611f\u5174\u8da3 \u2014 \u7279\u522b\u662f\u54cd\u5e94\u7c7b\u578b\u548c\u9519\u8bef\u4ee3\u7801\u3002\u56e0\u6b64\uff0c\u63cf\u8ff0\u6211\u4eec\u7684\u54cd\u5e94\u7c7b\u578b\u975e\u5e38\u91cd\u8981\u3002\u8fd9\u4e9b\u4f7f\u7528 XML \u6ce8\u91ca\u548c\u6570\u636e\u6ce8\u91ca\u8868\u793a\u3002<\/p>\n
Let\u2019s enhance the response types a little bit:
\n\u8ba9\u6211\u4eec\u7a0d\u5fae\u589e\u5f3a\u4e00\u4e0b\u54cd\u5e94\u7c7b\u578b\uff1a<\/p>\n
\/\/\/ <summary> \/\/\/ Creates a newly created company \/\/\/ <\/summary> \/\/\/ <param name="company"><\/param> \/\/\/ <returns>A newly created company<\/returns> \/\/\/ <response code="201">Returns the newly created item<\/response> \/\/\/ <response code="400">If the item is null<\/response> \/\/\/ <response code="422">If the model is invalid<\/response> [HttpPost(Name = "CreateCompany")] [ProducesResponseType(201)] [ProducesResponseType(400)] [ProducesResponseType(422)]<\/code><\/pre>\nHere, we are using both XML comments and data annotation attributes. Now, we can see the result:
\n\u5728\u8fd9\u91cc\uff0c\u6211\u4eec\u540c\u65f6\u4f7f\u7528\u4e86 XML \u6ce8\u91ca\u548c\u6570\u636e\u6ce8\u91ca\u5c5e\u6027\u3002\u73b0\u5728\uff0c\u6211\u4eec\u53ef\u4ee5\u770b\u5230\u7ed3\u679c\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3011.jpg\")
<\/p>\n
And, if we inspect the response part, we will find our mentioned responses:
\n\u800c\u4e14\uff0c\u5982\u679c\u6211\u4eec\u68c0\u67e5\u54cd\u5e94\u90e8\u5206\uff0c\u6211\u4eec\u4f1a\u627e\u5230\u6211\u4eec\u63d0\u5230\u7684\u54cd\u5e94\uff1a<\/p>\n
![\"alt](\"\/images\/ultimateaspnetcorewebapi6\/3012.jpg\")
<\/p>\n
Excellent.We can continue to the deployment part.
\n\u975e\u5e38\u597d\u3002\u6211\u4eec\u53ef\u4ee5\u7ee7\u7eed\u8fdb\u884c\u90e8\u7f72\u90e8\u5206\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"
30 DOCUMENTING API WITH SWAGGER 30 \u4f7f\u7528 SWAGGER \u7f16\u5199 API \u6587\u6863 Developers who consume our API might be trying to solve important business problems with it. Hence, it is very important for them to understand how to use our API effectively. This is where API documentation comes into the picture.\u200c \u4f7f\u7528\u6211\u4eec\u7684 API \u7684\u5f00\u53d1\u4eba\u5458\u53ef\u80fd\u6b63\u5728\u5c1d\u8bd5\u4f7f\u7528\u5b83\u6765\u89e3\u51b3\u91cd\u8981\u7684\u4e1a\u52a1\u95ee\u9898\u3002\u56e0\u6b64\uff0c\u4ed6\u4eec\u4e86\u89e3\u5982\u4f55\u6709\u6548\u5730\u4f7f\u7528\u6211\u4eec\u7684 API \u975e\u5e38\u91cd\u8981\u3002\u8fd9\u5c31\u662f […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1158","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/1158","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1158"}],"version-history":[{"count":0,"href":"https:\/\/diji.net\/index.php?rest_route=\/wp\/v2\/posts\/1158\/revisions"}],"wp:attachment":[{"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1158"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=1158"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/diji.net\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=1158"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}