Update web-api-help-pages-using-swagger.md (dotnet#20296)

Co-authored-by: Rick Anderson <[email protected]>
Co-authored-by: Scott Addie <[email protected]>

Author: 3 people

aspnetcore/tutorials/web-api-help-pages-using-swagger.md

@@ -1,32 +1,39 @@
 ---
-title: ASP.NET Core Web API help pages with Swagger / OpenAPI
+title: ASP.NET Core web API documentation with Swagger / OpenAPI
 author: RicoSuter
-description: This tutorial provides a walkthrough of adding Swagger to generate documentation and help pages for a Web API app.
+description: This tutorial provides a walkthrough of adding Swagger to generate documentation and help pages for a web API app.
 ms.author: scaddie
 ms.custom: mvc
-ms.date: 07/06/2020
+ms.date: 10/29/2020
 no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
 uid: tutorials/web-api-help-pages-using-swagger
 ---
-# ASP.NET Core web API help pages with Swagger / OpenAPI
+# ASP.NET Core web API documentation with Swagger / OpenAPI
 
 By [Christoph Nienaber](https://twitter.com/zuckerthoben) and [Rico Suter](https://blog.rsuter.com/)
 
-When consuming a web API, understanding its various methods can be challenging for a developer. [Swagger](https://swagger.io/), also known as [OpenAPI](https://www.openapis.org/), solves the problem of generating useful documentation and help pages for web APIs. It provides benefits such as interactive documentation, client SDK generation, and API discoverability.
+Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to:
 
-In this article, the [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) and [NSwag](https://github.com/RicoSuter/NSwag) .NET Swagger implementations are showcased:
+* Minimize the amount of work needed to connect decoupled services.
+* Reduce the amount of time needed to accurately document a service.
 
-* **Swashbuckle.AspNetCore** is an open source project for generating Swagger documents for ASP.NET Core Web APIs.
+The two main OpenAPI implementations for .NET are [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) and [NSwag](https://github.com/RicoSuter/NSwag), see:
 
-* **NSwag** is another open source project for generating Swagger documents and integrating [Swagger UI](https://swagger.io/swagger-ui/) or [ReDoc](https://github.com/Rebilly/ReDoc) into ASP.NET Core web APIs. Additionally, NSwag offers approaches to generate C# and TypeScript client code for your API.
+* [Getting Started with Swashbuckle](xref:tutorials/get-started-with-swashbuckle)
+* [Getting Started with NSwag](xref:tutorials/get-started-with-nswag)
 
-## What is Swagger / OpenAPI?
+## OpenApi vs. Swagger
 
-Swagger is a language-agnostic specification for describing [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs. The Swagger project was donated to the [OpenAPI Initiative](https://www.openapis.org/), where it's now referred to as OpenAPI. Both names are used interchangeably; however, OpenAPI is preferred. It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). One goal is to minimize the amount of work needed to connect disassociated services. Another goal is to reduce the amount of time needed to accurately document a service.
+The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Both names are used interchangeably. However, "OpenAPI" refers to the specification. "Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. Subsequent open-source products, such as [OpenAPIGenerator](https://github.com/OpenAPITools/openapi-generator), also fall under the Swagger family name, despite not being released by SmartBear.
+
+In short:
+
+* OpenAPI is a specification.
+* Swagger is tooling that uses the OpenAPI specification. For example, OpenAPIGenerator and SwaggerUI.
 
 ## OpenAPI specification (openapi.json)
 
-The core to the OpenAPI flow is the specification—by default, a document named *openapi.json*. It's generated by the OpenAPI tool chain (or third-party implementations of it) based on your service. It describes the capabilities of your API and how to access it with HTTP. It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. Here's an example of an OpenAPI specification, reduced for brevity:
+The OpenAPI specification is a document that describes the capabilities of your API. The document is based on the XML and attribute annotations within the controllers and models. It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. By default, it's named *openapi.json*. Here's an example of an OpenAPI specification, reduced for brevity:
 
 ```json
 {
@@ -120,7 +127,7 @@ The core to the OpenAPI flow is the specification—by default, a document n
 
 ![Swagger UI](web-api-help-pages-using-swagger/_static/swagger-ui.png)
 
-Each public action method in your controllers can be tested from the UI. Click a method name to expand the section. Add any necessary parameters, and click **Try it out!**.
+Each public action method in your controllers can be tested from the UI. Select a method name to expand the section. Add any necessary parameters, and select **Try it out!**.
 
 ![Example Swagger GET test](web-api-help-pages-using-swagger/_static/get-try-it-out.png)