apply changes from dotnet#34676

timdeschryver · Feb 19, 2025 · 2edb359 · 2edb359
1 parent f225fc8
commit 2edb359
Showing 1 changed file with 28 additions and 19 deletions.
diff --git a/aspnetcore/tutorials/first-web-api.md b/aspnetcore/tutorials/first-web-api.md
@@ -1,14 +1,14 @@
 ---
-title: "Tutorial: Create a web API with ASP.NET Core"
+title: "Tutorial: Create a controller-based web API with ASP.NET Core"
 author: wadepickett
-description: Learn how to build a web API with ASP.NET Core.
+description: Learn how to build a controller-based web API with ASP.NET Core.
 ms.author: wpickett
 ms.custom: mvc, engagement-fy24
 ms.date: 02/17/2025
 uid: tutorials/first-web-api
 ---
 
-# Tutorial: Create a web API with ASP.NET Core
+# Tutorial: Create a controller-based web API with ASP.NET Core
 
 [!INCLUDE[](~/includes/not-latest-version.md)]
 
@@ -46,7 +46,7 @@ The following diagram shows the design of the app.
 
 ---
 
-## Create a web project
+## Create a Web API project
 
 # [Visual Studio](#tab/visual-studio)
 
@@ -109,7 +109,11 @@ Visual Studio launches a terminal window and prints out the URL of the running a
    ```output
    ...
    info: Microsoft.Hosting.Lifetime[14]
-         Now listening on: https://localhost:{port}
+      Now listening on: https://localhost:7260
+   info: Microsoft.Hosting.Lifetime[14]
+      Now listening on: http://localhost:7261
+   info: Microsoft.Hosting.Lifetime[0]
+      Application started. Press Ctrl+C to shut down.
    ...
    ```
 
@@ -121,31 +125,31 @@ The browser displays JSON similar to the following example:
 ```json
 [
     {
-        "date": "2025-07-16T19:04:05.7257911-06:00",
+        "date": "2025-07-16",
         "temperatureC": 52,
         "temperatureF": 125,
         "summary": "Mild"
     },
     {
-        "date": "2025-07-17T19:04:05.7258461-06:00",
+        "date": "2025-07-17",
         "temperatureC": 36,
         "temperatureF": 96,
         "summary": "Warm"
     },
     {
-        "date": "2025-07-18T19:04:05.7258467-06:00",
+        "date": "2025-07-18",
         "temperatureC": 39,
         "temperatureF": 102,
         "summary": "Cool"
     },
     {
-        "date": "2025-07-19T19:04:05.7258471-06:00",
+        "date": "2025-07-19",
         "temperatureC": 10,
         "temperatureF": 49,
         "summary": "Bracing"
     },
     {
-        "date": "2025-07-20T19:04:05.7258474-06:00",
+        "date": "2025-07-20",
         "temperatureC": -1,
         "temperatureF": 31,
         "summary": "Chilly"
@@ -183,31 +187,31 @@ Run the app:
 ```json
 [
     {
-        "date": "2025-07-16T19:04:05.7257911-06:00",
+        "date": "2025-07-16",
         "temperatureC": 52,
         "temperatureF": 125,
         "summary": "Mild"
     },
     {
-        "date": "2025-07-17T19:04:05.7258461-06:00",
+        "date": "2025-07-17",
         "temperatureC": 36,
         "temperatureF": 96,
         "summary": "Warm"
     },
     {
-        "date": "2025-07-18T19:04:05.7258467-06:00",
+        "date": "2025-07-18",
         "temperatureC": 39,
         "temperatureF": 102,
         "summary": "Cool"
     },
     {
-        "date": "2025-07-19T19:04:05.7258471-06:00",
+        "date": "2025-07-19",
         "temperatureC": 10,
         "temperatureF": 49,
         "summary": "Bracing"
     },
     {
-        "date": "2025-07-20T19:04:05.7258474-06:00",
+        "date": "2025-07-20",
         "temperatureC": -1,
         "temperatureF": 31,
         "summary": "Chilly"
@@ -256,8 +260,12 @@ Because our project is using OpenAPI, we only use the NSwag package to generate
 
 :::code language="csharp" source="~/tutorials/first-web-api/samples/9.0/TodoApi_SwaggerVersion/Program.cs" id="snippet_UseSwagger":::
 
-  The previous code enables the Swagger middleware for serving the generated JSON document and the Swagger UI. Swagger is only enabled in a development environment. Enabling Swagger in a production environment could expose potentially sensitive details about the API's structure and implementation.
-  To generate the UI, it uses the OpenAPI document generated by OpenApi, located at `/openapi/v1.json`.
+The previous code enables the Swagger middleware for serving the generated JSON document using the Swagger UI. Swagger is only enabled in a development environment. Enabling Swagger in a production environment could expose potentially sensitive details about the API's structure and implementation.
+
+To generate the UI, it uses the OpenAPI document generated by OpenApi, located at `/openapi/v1.json`.
+View the generated OpenAPI specification for the `WeatherForecast` API while the project is running by navigating your browser to `https://localhost:<port>/openapi/v1.json`.
+
+The OpenAPI specification is a document in JSON format that describes the structure and capabilities of your API, including endpoints, request/response formats, parameters, and more. It's essentially a blueprint of your API that can be used by various tools to understand and interact with your API.
 
 ---
 
@@ -458,8 +466,8 @@ The <xref:Microsoft.AspNetCore.Mvc.ControllerBase.CreatedAtAction%2A> method:
   Content-Type: application/json
   
   {
-    "name":"walk dog",
-    "isComplete":true
+    "name": "walk dog",
+    "isComplete": true
   }
   
   ###
@@ -824,6 +832,7 @@ For more information, see the following resources:
 
 * <xref:web-api/index>
 * <xref:tutorials/min-web-api>
+* <xref:fundamentals/openapi/using-openapi-documents>
 * <xref:tutorials/web-api-help-pages-using-swagger>
 * <xref:data/ef-rp/intro>
 * <xref:mvc/controllers/routing>