diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx b/website/src/content/docs/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx index 40267bc99b8..a1efdfce16b 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx @@ -92,16 +92,14 @@ A REST service in TypeSpec is defined using the [`@service`](../../../standard-l Let's start by defining a simple REST service for a Pet Store: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={4-7} import "@typespec/http"; using Http; -// highlight-start @service(#{ title: "Pet Store", }) @server("https://example.com", "Single server endpoint") -// highlight-end ``` In this example: @@ -121,7 +119,7 @@ In this example: Let's create a namespace for our Pet Store service: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={8} import "@typespec/http"; using Http; @@ -129,7 +127,6 @@ using Http; @service(#{ title: "Pet Store" }) @server("https://example.com", "Single server endpoint") -// highlight-next-line namespace PetStore; ``` @@ -150,7 +147,7 @@ In TypeSpec, a [model](../../language-basics/models.md) is a fundamental buildin Let's define a simple model for a `Pet`: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={9-22} import "@typespec/http"; using Http; @@ -159,7 +156,6 @@ using Http; @server("https://example.com", "Single server endpoint") namespace PetStore; -// highlight-start model Pet { id: int32; name: string; @@ -174,7 +170,6 @@ enum petType { bird: "bird", reptile: "reptile", } -// highlight-end ``` In this example: @@ -189,7 +184,7 @@ In this example: We can add [validation](../../../language-basics/values/#validation) annotations to our model properties to enforce certain constraints: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={12,15-16} import "@typespec/http"; using Http; @@ -201,13 +196,10 @@ namespace PetStore; model Pet { id: int32; - // highlight-next-line @minLength(1) name: string; - // highlight-next-line @minValue(0) - // highlight-next-line @maxValue(100) age: int32; diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/02-operations-responses.md b/website/src/content/docs/docs/getting-started/getting-started-rest/02-operations-responses.md index 18650cc2109..215dfe89e0a 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/02-operations-responses.md +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/02-operations-responses.md @@ -17,7 +17,7 @@ Next, we'll discuss how to define CRUD operations for our API. We'll cover opera Let's define the CRUD operations for our `Pet` model: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={30-60} import "@typespec/http"; using Http; @@ -47,7 +47,6 @@ enum petType { reptile: "reptile", } -// highlight-start @route("/pets") namespace Pets { @get @@ -79,7 +78,6 @@ namespace Pets { @statusCode statusCode: 204; }; } -// highlight-end ``` In this example: @@ -138,7 +136,7 @@ In a real-world API, different operations might return different types of succes Let's update our pet operations to return different status codes based on the outcome. -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={42-43,50-52,59-60} import "@typespec/http"; using Http; @@ -180,31 +178,25 @@ namespace Pets { op getPet(@path petId: int32): { @statusCode statusCode: 200; @body pet: Pet; - // highlight-start } | { @statusCode statusCode: 404; - // highlight-end }; @post op createPet(@body pet: Pet): { @statusCode statusCode: 201; @body newPet: Pet; - // highlight-start } | { @statusCode statusCode: 202; @body acceptedPet: Pet; - // highlight-end }; @put op updatePet(@path petId: int32, @body pet: Pet): { @statusCode statusCode: 200; @body updatedPet: Pet; - // highlight-start } | { @statusCode statusCode: 404; - // highlight-end }; @delete diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/03-handling-errors.md b/website/src/content/docs/docs/getting-started/getting-started-rest/03-handling-errors.md index 6aa893c46a8..2e98ad8d227 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/03-handling-errors.md +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/03-handling-errors.md @@ -26,7 +26,7 @@ Error models can be used to represent different types of errors that your API mi We'll define models to represent validation errors, not-found errors, and internal server errors: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={45,55-58,65-76,85-102} import "@typespec/http"; using Http; @@ -71,7 +71,6 @@ namespace Pets { } | { @statusCode statusCode: 404; - // highlight-next-line @body error: NotFoundError; }; @@ -82,19 +81,16 @@ namespace Pets { } | { @statusCode statusCode: 202; @body acceptedPet: Pet; - // highlight-start } | { @statusCode statusCode: 400; @body error: ValidationError; }; - // highlight-end @put op updatePet(@path petId: int32, @body pet: Pet): | { @statusCode statusCode: 200; @body updatedPet: Pet; - // highlight-start } | { @statusCode statusCode: 400; @@ -107,7 +103,6 @@ namespace Pets { | { @statusCode statusCode: 500; @body error: InternalServerError; - // highlight-end }; @delete @@ -116,7 +111,6 @@ namespace Pets { }; } -// highlight-start @error model NotFoundError { code: "NOT_FOUND"; @@ -135,7 +129,6 @@ model InternalServerError { code: "INTERNAL_SERVER_ERROR"; message: string; } -// highlight-end ``` In this example: diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/04-common-parameters.md b/website/src/content/docs/docs/getting-started/getting-started-rest/04-common-parameters.md index 665421e8d0a..931ef3008ab 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/04-common-parameters.md +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/04-common-parameters.md @@ -16,7 +16,7 @@ Let's start by defining a model for common parameters. This model will include p For the sake of demonstration, we're going to require each API call in our Pet Store service to include a request ID, a locale, and a client version. Let's define a model for these common parameters, which we'll label `requestID`, `locale`, and `clientVersion`: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={30-39} import "@typespec/http"; using Http; @@ -46,7 +46,6 @@ enum petType { reptile: "reptile", } -// highlight-start model CommonParameters { @header requestID: string; @@ -57,7 +56,6 @@ model CommonParameters { @header clientVersion?: string; } -// highlight-end ``` In this example: @@ -71,7 +69,7 @@ Now that we have defined our common parameters model, let's reuse it across mult ### Example: Reusing Common Parameters in Operations -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={44,50,59,71,90} import "@typespec/http"; using Http; @@ -115,14 +113,12 @@ model CommonParameters { @route("/pets") namespace Pets { @get - // highlight-next-line op listPets(...CommonParameters): { @statusCode statusCode: 200; @body pets: Pet[]; }; @get - // highlight-next-line op getPet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 200; @body pet: Pet; @@ -132,7 +128,6 @@ namespace Pets { }; @post - // highlight-next-line op createPet(@body pet: Pet, ...CommonParameters): { @statusCode statusCode: 201; @body newPet: Pet; @@ -145,7 +140,6 @@ namespace Pets { }; @put - // highlight-next-line op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): | { @statusCode statusCode: 200; @@ -165,7 +159,6 @@ namespace Pets { }; @delete - // highlight-next-line op deletePet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 204; }; @@ -200,7 +193,7 @@ In this example: Let's take a closer look at how the common parameters model with the `spread` operator is represented in the generated OpenAPI specification by looking at the `deletePet` operation: -```yaml +```yaml mark={14-16,28-45} #### Generated OpenAPI Specification: paths: @@ -214,11 +207,9 @@ paths: schema: type: integer format: int32 - // highlight-start - $ref: "#/components/parameters/CommonParameters.requestID" - $ref: "#/components/parameters/CommonParameters.locale" - $ref: "#/components/parameters/CommonParameters.clientVersion" - // highlight-end responses: "204": description: "There is no content to send for this request, but the headers may be useful." @@ -230,7 +221,6 @@ paths: $ref: "#/components/schemas/NotFoundError" components: parameters: - // highlight-start CommonParameters.clientVersion: name: client-version in: header @@ -249,7 +239,6 @@ components: required: true schema: type: string - // highlight-end schemas: NotFoundError: type: object diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/05-authentication.md b/website/src/content/docs/docs/getting-started/getting-started-rest/05-authentication.md index f1937fb8798..98ebf287f7e 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/05-authentication.md +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/05-authentication.md @@ -18,7 +18,7 @@ Bearer authentication uses tokens for access control. The server generates a tok Let's update our existing operations by enforcing authentication using the `@useAuth` decorator.We'll add authentication to the operations that modify pet data, such as creating, updating, and deleting pets. We'll also add a new error model for unauthorized access. -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={59,72-75,79,90-92,104,107-109,126-130} import "@typespec/http"; using Http; @@ -77,7 +77,6 @@ namespace Pets { }; @post - // highlight-next-line @useAuth(BearerAuth) op createPet(@body pet: Pet, ...CommonParameters): | { @@ -91,16 +90,13 @@ namespace Pets { | { @statusCode statusCode: 400; @body error: ValidationError; - // highlight-start } | { @statusCode statusCode: 401; @body error: UnauthorizedError; - // highlight-end }; @put - // highlight-next-line @useAuth(BearerAuth) op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): | { @@ -112,11 +108,9 @@ namespace Pets { @body error: ValidationError; } | { - // highlight-start @statusCode statusCode: 401; @body error: UnauthorizedError; - // highlight-end } | { @statusCode statusCode: 404; @@ -128,15 +122,12 @@ namespace Pets { }; @delete - // highlight-next-line @useAuth(BearerAuth) op deletePet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 204; - // highlight-start } | { @statusCode statusCode: 401; @body error: UnauthorizedError; - // highlight-end }; } @@ -153,13 +144,11 @@ model ValidationError { details: string[]; } -// highlight-start @error model UnauthorizedError { code: "UNAUTHORIZED"; message: string; } -// highlight-end @error model InternalServerError { @@ -183,7 +172,7 @@ In this example: Let's take a closer look at how the `@useAuth` decorator affects the generated OpenAPI specification for the `deletePet` operation. -```yaml +```yaml mark={15-16,46-49} paths: /pets/{petId}: delete: @@ -198,10 +187,8 @@ paths: - $ref: "#/components/parameters/CommonParameters.requestID" - $ref: "#/components/parameters/CommonParameters.locale" - $ref: "#/components/parameters/CommonParameters.clientVersion" - // highlight-start security: - BearerAuth: [] - // highlight-end responses: "204": description: "There is no content to send for this request, but the headers may be useful." @@ -231,12 +218,10 @@ components: required: true schema: type: string - // highlight-start securitySchemes: BearerAuth: type: http scheme: bearer - // highlight-end schemas: NotFoundError: type: object diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/06-versioning.mdx b/website/src/content/docs/docs/getting-started/getting-started-rest/06-versioning.mdx index 41d61f9c0a3..860b816cae2 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/06-versioning.mdx +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/06-versioning.mdx @@ -18,7 +18,7 @@ Before we can use the versioning decorators, we need to add the `@typespec/versi Add the `@typespec/versioning` library to your `package.json` file, in both the `peerDependencies` and `devDependencies` sections. Your updated `package.json` should look like this: -```json +```json mark={9,15} { "name": "typespec-petstore", "version": "0.1.0", @@ -27,14 +27,12 @@ Add the `@typespec/versioning` library to your `package.json` file, in both the "@typespec/compiler": "latest", "@typespec/http": "latest", "@typespec/openapi3": "latest", - // highlight-next-line "@typespec/versioning": "latest" }, "devDependencies": { "@typespec/compiler": "latest", "@typespec/http": "latest", "@typespec/openapi3": "latest", - // highlight-next-line "@typespec/versioning": "latest" }, "private": true @@ -57,27 +55,22 @@ The [`@versioned`](../../../libraries/versioning/reference/decorators/#@TypeSpec Let's define two versions of our API, `v1` and `v2`: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={2,5,9,12-15} import "@typespec/http"; -// highlight-next-line import "@typespec/versioning"; using Http; -// highlight-next-line using Versioning; @service(#{ title: "Pet Store" }) @server("https://example.com", "Single server endpoint") -// highlight-next-line @versioned(Versions) namespace PetStore; -// highlight-start enum Versions { v1: "1.0", v2: "2.0", } -// highlight-end ``` In this example: @@ -115,7 +108,7 @@ The [`@added`](../../../libraries/versioning/reference/decorators/#@TypeSpec.Ver Let's add a `Toy` model that is only available in version 2 of the API: -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={38-42} import "@typespec/http"; import "@typespec/versioning"; @@ -153,13 +146,11 @@ enum petType { reptile: "reptile", } -// highlight-start @added(Versions.v2) model Toy { id: int32; name: string; } -// highlight-end ``` In this example: @@ -172,7 +163,7 @@ Let's define version-specific operations to manage toys for pets. These operatio ### Example: Adding Version-Specific Operations -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={125-180} import "@typespec/http"; import "@typespec/versioning"; @@ -297,7 +288,6 @@ namespace Pets { @body error: UnauthorizedError; }; - // highlight-start @route("{petId}/toys") namespace Toys { @added(Versions.v2) @@ -354,7 +344,6 @@ namespace Pets { @body error: UnauthorizedError; }; } - // highlight-end } @error diff --git a/website/src/content/docs/docs/getting-started/getting-started-rest/07-custom-response-models.md b/website/src/content/docs/docs/getting-started/getting-started-rest/07-custom-response-models.md index f26fadc8231..32b97c979a9 100644 --- a/website/src/content/docs/docs/getting-started/getting-started-rest/07-custom-response-models.md +++ b/website/src/content/docs/docs/getting-started/getting-started-rest/07-custom-response-models.md @@ -98,7 +98,7 @@ Now that we have defined our custom response models, let's use them in our API o ### Example: Applying Custom Response Models to Operations -```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" +```tsp title=main.tsp tryit="{"emit": ["@typespec/openapi3"]}" mark={55-97,102,105,108-112,116-121,125} import "@typespec/http"; import "@typespec/versioning"; @@ -153,7 +153,6 @@ model CommonParameters { clientVersion?: string; } -// highlight-start model PetListResponse { ...OkResponse; ...Body; @@ -197,44 +196,34 @@ model PetSuccessResponse { model PetNoContentResponse { ...NoContentResponse; } -// highlight-end @route("/pets") namespace Pets { @get - // highlight-next-line op listPets(...CommonParameters): PetListResponse; @get - // highlight-start op getPet(@path petId: int32, @header ifMatch?: string): PetResponse | PetNotFoundResponse; - // highlight-end @useAuth(BearerAuth) @post - // highlight-start op createPet(@body pet: Pet): | PetCreatedResponse | PetAcceptedResponse | PetErrorResponse | PetUnauthorizedResponse; - // highlight-end @useAuth(BearerAuth) @put - // highlight-start op updatePet(@path petId: int32, @body pet: Pet): | PetResponse | PetErrorResponse | PetUnauthorizedResponse | PetNotFoundResponse | InternalServerErrorResponse; - // highlight-end @useAuth(BearerAuth) @delete - // highlight-start op deletePet(@path petId: int32): PetNoContentResponse | PetUnauthorizedResponse; - // highlight-end @route("{petId}/toys") namespace Toys {