From d705dd53b4cd2e7f91aa1baafb976943621f3c55 Mon Sep 17 00:00:00 2001 From: Mario Guerra <85648637+mario-guerra@users.noreply.github.com> Date: Wed, 17 Jul 2024 12:25:51 -0500 Subject: [PATCH] minor edits and corrections (#3841) --- .../04-resources-routes-status.md | 11 ++--------- .../getting-started-http/06-path-query-parameters.md | 2 +- .../getting-started-http/09-interfaces.md | 2 +- .../{11-summary.md => 11-complete-example.md} | 6 ++---- 4 files changed, 6 insertions(+), 15 deletions(-) rename docs/getting-started/getting-started-http/{11-summary.md => 11-complete-example.md} (98%) diff --git a/docs/getting-started/getting-started-http/04-resources-routes-status.md b/docs/getting-started/getting-started-http/04-resources-routes-status.md index cdd3451a73..e700a90f99 100644 --- a/docs/getting-started/getting-started-http/04-resources-routes-status.md +++ b/docs/getting-started/getting-started-http/04-resources-routes-status.md @@ -66,16 +66,11 @@ Here are some common HTTP status codes and their meanings: The `@statusCode` decorator is used to specify the status code for a response. You can use number literal types to create a discriminated union of response types, allowing you to handle different status codes in a single operation. -Let's add `list` and `create` operations to our `Pets` resource and use the `@statusCode` decorator to specify the status codes for each operation. +Let's add a `create` operation to our `Pets` resource and use the `@statusCode` decorator to specify the status codes for a successful operation. ```typespec @route("/pets") namespace Pets { - op list(@query skip: int32, @query top: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; - @post op create(@body pet: Pet): { @statusCode statusCode: 201; @@ -86,7 +81,7 @@ namespace Pets { } ``` -**Note**: The `@body` decorator and error handling are introduced here but will be covered in detail in later sections. +**Note**: This example introduces a `@body` decorator and error handling, which will be covered in detail in later sections. ### Handling Multiple Status Codes @@ -107,8 +102,6 @@ namespace Pets { } ``` -We'll cover error handling in more detail in the next section. - In this example: - The `create` operation returns a `201 Created` status code when a new pet is successfully created. diff --git a/docs/getting-started/getting-started-http/06-path-query-parameters.md b/docs/getting-started/getting-started-http/06-path-query-parameters.md index dfeccfa389..ab166c2031 100644 --- a/docs/getting-started/getting-started-http/06-path-query-parameters.md +++ b/docs/getting-started/getting-started-http/06-path-query-parameters.md @@ -31,7 +31,7 @@ In this example, `petId` is a path parameter. The resulting URL for this operati Query parameters are used to filter or modify the results of an operation. They are marked with the `@query` decorator and are appended to the URL as key-value pairs. -For example, let's modify our `list` operation to support pagination using query parameters: +For example, let's add a `list` operation that supports pagination using query parameters: ```typespec @route("/pets") diff --git a/docs/getting-started/getting-started-http/09-interfaces.md b/docs/getting-started/getting-started-http/09-interfaces.md index 1932d70704..fa0c698e81 100644 --- a/docs/getting-started/getting-started-http/09-interfaces.md +++ b/docs/getting-started/getting-started-http/09-interfaces.md @@ -21,7 +21,7 @@ interface ToyOperations { } ``` -In this example, the `ToyOperations` interface defines two operations: `getToy` and `updateToy`. The `@added(Versions.v2)` decorator indicates that these operations are part of version 2 of the service. +In this example, the `ToyOperations` interface defines two operations: `getToy` and `updateToy`. The `@added(Versions.v2)` decorator indicates that these operations are part of version 2 of the service. We're also making use of the `NotFoundError` defined earlier to handle cases where a toy is not found. ## Using Interfaces diff --git a/docs/getting-started/getting-started-http/11-summary.md b/docs/getting-started/getting-started-http/11-complete-example.md similarity index 98% rename from docs/getting-started/getting-started-http/11-summary.md rename to docs/getting-started/getting-started-http/11-complete-example.md index 8acc9041c1..2b7151f379 100644 --- a/docs/getting-started/getting-started-http/11-summary.md +++ b/docs/getting-started/getting-started-http/11-complete-example.md @@ -1,15 +1,13 @@ --- -title: Summary +title: Complete Example --- -# Summary +# Complete Example In this tutorial, we have covered the basics of creating a REST API definition using TypeSpec. We started by setting up a new TypeSpec project and then defined a Pet Store service with various operations. We explored how to use decorators to define routes, handle path and query parameters, manage headers, and specify request and response bodies. We also looked at how to automatically generate routes, define status codes, handle errors, and manage versioning. By following these steps, you should now have a good understanding of how to use TypeSpec to define and manage your HTTP APIs. For more advanced features and detailed documentation, refer to the official TypeSpec documentation and community resources. -## Complete Code Example - Here's the complete Pet Store service definition written in TypeSpec: ```tsp tryit="{"emit": ["@typespec/openapi3"]}"