From 1455928d258ae18f615ca24a1caec9d60f14bb01 Mon Sep 17 00:00:00 2001 From: Christopher Radek <14189820+chrisradek@users.noreply.github.com> Date: Wed, 7 Aug 2024 21:54:25 -0700 Subject: [PATCH] TypeSpec 0.59 - August 2024 Release branch (#4120) Co-authored-by: Christopher Radek --- .../changes/Issue3601-2024-6-18-17-42-35.md | 7 - ...del-previous-version-2024-6-19-18-50-40.md | 8 - ...mplate-parameter-ref-2024-6-19-15-17-25.md | 16 - .../changes/docs-servers-2024-6-24-14-48-1.md | 6 - ...ode-numeric-as-string-2024-6-25-20-9-18.md | 10 - ...sh-spread-versioning-2024-6-23-14-37-28.md | 7 - .../changes/fix-get-doc-2024-6-17-16-36-18.md | 7 - .../fix-multipart-name-2024-6-19-17-57-10.md | 8 - ...mespace-in-blockless-2024-6-30-10-29-59.md | 14 - ...mespace-in-blockless-2024-6-30-10-31-17.md | 33 -- ...umeric-leading-zeros-2024-6-18-19-57-12.md | 8 - ...cular-ref-regression-2024-6-31-14-17-20.md | 6 - ...ix-response-examples-2024-6-29-22-38-45.md | 8 - ...ix-response-examples-2024-6-30-15-26-28.md | 7 - ...ix-response-examples-2024-6-30-15-59-29.md | 8 - ...fix-response-examples-2024-6-30-22-22-9.md | 8 - ...fix-server-js-version-2024-6-24-10-1-25.md | 6 - .../fix-tsp-default-csv1-2024-7-7-14-31-14.md | 6 - ...-encode-reserved-char-2024-7-6-18-53-32.md | 6 - ...nv-openapi3-circ-ref-2024-6-19-13-33-42.md | 7 - ...hema-extension-values-2024-6-16-9-43-39.md | 34 -- ...ernal-compiler-error-2024-6-25-21-39-16.md | 8 - .../changes/lib-const-2024-6-22-22-3-25.md | 8 - .../changes/lib-const-2024-6-22-22-3-26.md | 10 - ...-set-root-extensions-2024-6-18-19-20-36.md | 7 - ...3-fix-circ-ref-unions-2024-6-19-10-0-54.md | 7 - .../path-unix-style-2024-6-25-15-13-16.md | 7 - ...factor-shared-routes-2024-6-29-19-52-22.md | 8 - .../service-csharp-2024-1-12-3-50-33.md | 8 - ...erate-interface-sigs-2024-6-19-15-34-36.md | 9 - ...ade-deps-july-2024-2-2024-6-22-23-39-34.md | 26 -- .../uri-templates-2024-6-24-20-7-39.md | 12 - .../uri-templates-2024-6-24-21-37-52.md | 9 - .../uri-templates-2024-6-25-9-3-39-2.md | 7 - .../changes/uri-templates-2024-6-25-9-3-39.md | 13 - .../uri-templates-2024-7-6-16-39-59.md | 8 - ...sft-hsj-petstore-fixes-2024-7-6-16-28-8.md | 7 - ...-hsj-router-param-bug-2024-7-7-15-20-46.md | 8 - packages/bundler/CHANGELOG.md | 7 + packages/bundler/package.json | 2 +- packages/compiler/CHANGELOG.md | 69 ++++ packages/compiler/package.json | 2 +- packages/compiler/templates/scaffolding.json | 8 +- packages/eslint-plugin-typespec/CHANGELOG.md | 7 + packages/eslint-plugin-typespec/package.json | 2 +- packages/html-program-viewer/CHANGELOG.md | 7 + packages/html-program-viewer/package.json | 2 +- packages/http-server-csharp/CHANGELOG.md | 4 + packages/http-server-csharp/package.json | 2 +- packages/http-server-javascript/CHANGELOG.md | 13 + packages/http-server-javascript/package.json | 2 +- packages/http/CHANGELOG.md | 32 ++ packages/http/package.json | 2 +- packages/internal-build-utils/CHANGELOG.md | 7 + packages/internal-build-utils/package.json | 2 +- packages/json-schema/CHANGELOG.md | 38 ++ packages/json-schema/package.json | 2 +- packages/library-linter/CHANGELOG.md | 7 + packages/library-linter/package.json | 2 +- packages/openapi/CHANGELOG.md | 7 + packages/openapi/package.json | 2 +- packages/openapi3/CHANGELOG.md | 21 ++ packages/openapi3/package.json | 2 +- packages/playground/CHANGELOG.md | 7 + packages/playground/package.json | 2 +- .../prettier-plugin-typespec/CHANGELOG.md | 7 + .../prettier-plugin-typespec/package.json | 2 +- packages/protobuf/CHANGELOG.md | 11 + packages/protobuf/package.json | 2 +- packages/rest/CHANGELOG.md | 11 + packages/rest/package.json | 2 +- packages/tmlanguage-generator/CHANGELOG.md | 7 + packages/tmlanguage-generator/package.json | 2 +- packages/typespec-vs/CHANGELOG.md | 7 + packages/typespec-vs/package.json | 2 +- packages/typespec-vscode/CHANGELOG.md | 7 + packages/typespec-vscode/package.json | 2 +- packages/versioning/CHANGELOG.md | 12 + packages/versioning/package.json | 2 +- packages/website/playground-versions.json | 1 + .../json-schema/reference/data-types.md | 21 ++ .../json-schema/reference/decorators.md | 28 +- .../reference/js-api/functions/$extension.md | 2 +- .../js-api/functions/setExtension.md | 25 ++ .../json-schema/reference/js-api/index.md | 1 + .../js-api/interfaces/ExtensionRecord.md | 2 +- .../reference/js-api/variables/$lib.md | 6 +- .../reference/js-api/variables/$lib.md | 4 + .../emitters/protobuf/reference/data-types.md | 7 + .../reference/js-api/functions/$field.md | 2 + .../reference/js-api/variables/$lib.md | 56 +-- .../getting-started-http/00-index.md | 19 - .../getting-started-http/01-setup.md | 27 -- .../02-service-definition.md | 41 --- .../getting-started-http/03-versioning.md | 43 --- .../04-resources-routes-status.md | 117 ------ .../getting-started-http/05-error-handling.md | 60 --- .../06-path-query-parameters.md | 75 ---- .../getting-started-http/07-headers.md | 116 ------ .../08-request-response-bodies.md | 156 -------- .../getting-started-http/09-interfaces.md | 30 -- .../10-automatic-route-generation.md | 76 ---- .../getting-started-http/11-summary.md | 177 --------- .../01-setup-basic-syntax.md | 336 +++++++++++++++++ .../02-operations-responses.md | 345 ++++++++++++++++++ .../03-handling-errors.md | 338 +++++++++++++++++ .../04-common-parameters.md | 195 ++++++++++ .../getting-started-rest/05-authentication.md | 142 +++++++ .../getting-started-rest/06-versioning.md | 330 +++++++++++++++++ .../07-custom-response-models.md | 287 +++++++++++++++ .../getting-started-rest/08-conclusion.md | 33 ++ .../getting-started/getting-started.md | 3 +- .../introduction/installation.md | 22 +- .../version-latest/libraries/http/encoding.md | 38 ++ .../version-latest/libraries/http/examples.md | 30 ++ .../libraries/http/operations.md | 2 +- .../libraries/http/reference/data-types.md | 45 ++- .../libraries/http/reference/decorators.md | 75 ++-- .../libraries/http/reference/index.mdx | 1 + .../http/reference/js-api/functions/$path.md | 4 +- .../http/reference/js-api/functions/$query.md | 2 +- .../functions/getOperationParameters.md | 16 +- .../js-api/functions/joinPathSegments.md | 18 + .../functions/resolvePathAndParameters.md | 2 +- .../libraries/http/reference/js-api/index.md | 5 + .../js-api/interfaces/HeaderFieldOptions.md | 2 +- .../js-api/interfaces/HttpOperation.md | 25 +- .../interfaces/HttpOperationParameters.md | 13 +- .../HttpOperationResponseContent.md | 9 +- .../js-api/interfaces/PathParameterOptions.md | 15 +- .../interfaces/QueryParameterOptions.md | 15 +- .../js-api/interfaces/RouteProducerResult.md | 2 +- .../HttpOperationHeaderParameter.md | 14 + .../type-aliases/HttpOperationParameter.md | 8 +- .../HttpOperationPathParameter.md | 14 + .../HttpOperationQueryParameter.md | 14 + .../js-api/type-aliases/HttpProperty.md | 17 + .../http/reference/js-api/variables/$lib.md | 32 +- .../js-api/interfaces/XmlEncodeData.md | 8 +- .../release-notes/release-2024-08-06.md | 164 +++++++++ .../standard-library/built-in-data-types.md | 29 ++ .../standard-library/built-in-decorators.md | 22 +- .../standard-library/examples.md | 103 ++++++ .../standard-library/projected-names.md | 146 -------- .../reference/js-api/functions/$encode.md | 4 +- .../reference/js-api/functions/$example.md | 2 +- .../reference/js-api/functions/$opExample.md | 4 +- .../js-api/functions/cadlTypeToJson.md | 7 +- .../js-api/functions/checkFormatCadl.md | 6 +- .../js-api/functions/createCadlLibrary.md | 21 +- .../js-api/functions/isCadlValueTypeOf.md | 6 +- .../js-api/functions/setCadlNamespace.md | 6 +- .../reference/js-api/interfaces/EncodeData.md | 8 +- .../js-api/type-aliases/CadlLibrary.md | 8 +- .../js-api/type-aliases/CadlLibraryDef.md | 8 +- .../js-api/type-aliases/InferredCadlValue.md | 8 +- .../version-latest-sidebars.json | 13 +- packages/xml/CHANGELOG.md | 11 + packages/xml/package.json | 2 +- 159 files changed, 3144 insertions(+), 1701 deletions(-) delete mode 100644 .chronus/changes/Issue3601-2024-6-18-17-42-35.md delete mode 100644 .chronus/changes/allow-spreading-model-previous-version-2024-6-19-18-50-40.md delete mode 100644 .chronus/changes/complete-template-parameter-ref-2024-6-19-15-17-25.md delete mode 100644 .chronus/changes/docs-servers-2024-6-24-14-48-1.md delete mode 100644 .chronus/changes/encode-numeric-as-string-2024-6-25-20-9-18.md delete mode 100644 .chronus/changes/fix-crash-spread-versioning-2024-6-23-14-37-28.md delete mode 100644 .chronus/changes/fix-get-doc-2024-6-17-16-36-18.md delete mode 100644 .chronus/changes/fix-multipart-name-2024-6-19-17-57-10.md delete mode 100644 .chronus/changes/fix-namespace-in-blockless-2024-6-30-10-29-59.md delete mode 100644 .chronus/changes/fix-namespace-in-blockless-2024-6-30-10-31-17.md delete mode 100644 .chronus/changes/fix-numeric-leading-zeros-2024-6-18-19-57-12.md delete mode 100644 .chronus/changes/fix-openapi3-circular-ref-regression-2024-6-31-14-17-20.md delete mode 100644 .chronus/changes/fix-response-examples-2024-6-29-22-38-45.md delete mode 100644 .chronus/changes/fix-response-examples-2024-6-30-15-26-28.md delete mode 100644 .chronus/changes/fix-response-examples-2024-6-30-15-59-29.md delete mode 100644 .chronus/changes/fix-response-examples-2024-6-30-22-22-9.md delete mode 100644 .chronus/changes/fix-server-js-version-2024-6-24-10-1-25.md delete mode 100644 .chronus/changes/fix-tsp-default-csv1-2024-7-7-14-31-14.md delete mode 100644 .chronus/changes/fix-uri-template-encode-reserved-char-2024-7-6-18-53-32.md delete mode 100644 .chronus/changes/inv-openapi3-circ-ref-2024-6-19-13-33-42.md delete mode 100644 .chronus/changes/json-schema-extension-values-2024-6-16-9-43-39.md delete mode 100644 .chronus/changes/keep-watch-internal-compiler-error-2024-6-25-21-39-16.md delete mode 100644 .chronus/changes/lib-const-2024-6-22-22-3-25.md delete mode 100644 .chronus/changes/lib-const-2024-6-22-22-3-26.md delete mode 100644 .chronus/changes/mk-set-root-extensions-2024-6-18-19-20-36.md delete mode 100644 .chronus/changes/openapi3-fix-circ-ref-unions-2024-6-19-10-0-54.md delete mode 100644 .chronus/changes/path-unix-style-2024-6-25-15-13-16.md delete mode 100644 .chronus/changes/refactor-shared-routes-2024-6-29-19-52-22.md delete mode 100644 .chronus/changes/service-csharp-2024-1-12-3-50-33.md delete mode 100644 .chronus/changes/tspd-generate-interface-sigs-2024-6-19-15-34-36.md delete mode 100644 .chronus/changes/upgrade-deps-july-2024-2-2024-6-22-23-39-34.md delete mode 100644 .chronus/changes/uri-templates-2024-6-24-20-7-39.md delete mode 100644 .chronus/changes/uri-templates-2024-6-24-21-37-52.md delete mode 100644 .chronus/changes/uri-templates-2024-6-25-9-3-39-2.md delete mode 100644 .chronus/changes/uri-templates-2024-6-25-9-3-39.md delete mode 100644 .chronus/changes/uri-templates-2024-7-6-16-39-59.md delete mode 100644 .chronus/changes/witemple-msft-hsj-petstore-fixes-2024-7-6-16-28-8.md delete mode 100644 .chronus/changes/witemple-msft-hsj-router-param-bug-2024-7-7-15-20-46.md create mode 100644 packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/setExtension.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/00-index.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/01-setup.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/02-service-definition.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/03-versioning.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/04-resources-routes-status.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/05-error-handling.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/06-path-query-parameters.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/07-headers.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/08-request-response-bodies.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/09-interfaces.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/10-automatic-route-generation.md delete mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-http/11-summary.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/01-setup-basic-syntax.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/02-operations-responses.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/03-handling-errors.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/04-common-parameters.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/05-authentication.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/06-versioning.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/07-custom-response-models.md create mode 100644 packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/08-conclusion.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/examples.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/joinPathSegments.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationHeaderParameter.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationPathParameter.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationQueryParameter.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpProperty.md create mode 100644 packages/website/versioned_docs/version-latest/release-notes/release-2024-08-06.md create mode 100644 packages/website/versioned_docs/version-latest/standard-library/examples.md delete mode 100644 packages/website/versioned_docs/version-latest/standard-library/projected-names.md diff --git a/.chronus/changes/Issue3601-2024-6-18-17-42-35.md b/.chronus/changes/Issue3601-2024-6-18-17-42-35.md deleted file mode 100644 index b928260e5f..0000000000 --- a/.chronus/changes/Issue3601-2024-6-18-17-42-35.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: feature -packages: - - "@typespec/openapi3" ---- - -Add support for `@useRef` on responses \ No newline at end of file diff --git a/.chronus/changes/allow-spreading-model-previous-version-2024-6-19-18-50-40.md b/.chronus/changes/allow-spreading-model-previous-version-2024-6-19-18-50-40.md deleted file mode 100644 index ab7ab21daf..0000000000 --- a/.chronus/changes/allow-spreading-model-previous-version-2024-6-19-18-50-40.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/versioning" ---- - -Allow spreading a model that has props added in previous version diff --git a/.chronus/changes/complete-template-parameter-ref-2024-6-19-15-17-25.md b/.chronus/changes/complete-template-parameter-ref-2024-6-19-15-17-25.md deleted file mode 100644 index 36c96ded18..0000000000 --- a/.chronus/changes/complete-template-parameter-ref-2024-6-19-15-17-25.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Support completion for template parameter extending model or object value - - Example - ```tsp - model User { - } - alias user = User< {┆ - | [age] - | [name] - ``` diff --git a/.chronus/changes/docs-servers-2024-6-24-14-48-1.md b/.chronus/changes/docs-servers-2024-6-24-14-48-1.md deleted file mode 100644 index 29944196b6..0000000000 --- a/.chronus/changes/docs-servers-2024-6-24-14-48-1.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/http" ---- - diff --git a/.chronus/changes/encode-numeric-as-string-2024-6-25-20-9-18.md b/.chronus/changes/encode-numeric-as-string-2024-6-25-20-9-18.md deleted file mode 100644 index 8ecec9e7c0..0000000000 --- a/.chronus/changes/encode-numeric-as-string-2024-6-25-20-9-18.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" - - "@typespec/openapi3" - - "@typespec/xml" ---- - -Add support for encoding numeric types as string diff --git a/.chronus/changes/fix-crash-spread-versioning-2024-6-23-14-37-28.md b/.chronus/changes/fix-crash-spread-versioning-2024-6-23-14-37-28.md deleted file mode 100644 index 662d0e47f5..0000000000 --- a/.chronus/changes/fix-crash-spread-versioning-2024-6-23-14-37-28.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/versioning" ---- - -Fixes issue where spreading a versioned model as a parameter to an incompatible versioned operation would cause the compiler to crash. \ No newline at end of file diff --git a/.chronus/changes/fix-get-doc-2024-6-17-16-36-18.md b/.chronus/changes/fix-get-doc-2024-6-17-16-36-18.md deleted file mode 100644 index d9dd756e6b..0000000000 --- a/.chronus/changes/fix-get-doc-2024-6-17-16-36-18.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fixes a bug where ending a non-terminal line in a multi-line comment with a backslash caused the next star to show up in the parsed doc string. \ No newline at end of file diff --git a/.chronus/changes/fix-multipart-name-2024-6-19-17-57-10.md b/.chronus/changes/fix-multipart-name-2024-6-19-17-57-10.md deleted file mode 100644 index 814681fb27..0000000000 --- a/.chronus/changes/fix-multipart-name-2024-6-19-17-57-10.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/http" ---- - -Fix `HttpPart` not respecting explicit part name by always using the property name diff --git a/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-29-59.md b/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-29-59.md deleted file mode 100644 index 74ecf7faa5..0000000000 --- a/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-29-59.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Allow using compact namespace form `Foo.Bar` when inside another namespace - ```tsp - namespace MyOrg.MyProject { - namespace MyModule.MySubmodule { // <-- this used to emit an error - // ... - } - } - ``` diff --git a/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-31-17.md b/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-31-17.md deleted file mode 100644 index 11ee6c6cb9..0000000000 --- a/.chronus/changes/fix-namespace-in-blockless-2024-6-30-10-31-17.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -changeKind: breaking -packages: - - "@typespec/compiler" ---- - -Fix issue where naming a namespace with the same name as the blockless namespace would merge with it instead of creating a subnamespace like any other name would. - - ```tsp - namespace MyOrg.MyProject; - - namespace MyOrg.MyProject.MyArea { - model A {} - } - - namespace MyArea2 { - model B {} - } - ``` - - Previously model `A` would end-up in namespace `MyOrg.MyProject.MyArea` and model `B` in `MyOrg.MyProject.MyArea2`. With this change model `A` will now be in `MyOrg.MyProject.MyOrg.MyProject.MyArea`. To achieve the previous behavior the above code should be written as: - - ```tsp - namespace MyOrg.MyProject; - - namespace MyArea { - model A {} - } - - namespace MyArea2 { - model B {} - } - ``` diff --git a/.chronus/changes/fix-numeric-leading-zeros-2024-6-18-19-57-12.md b/.chronus/changes/fix-numeric-leading-zeros-2024-6-18-19-57-12.md deleted file mode 100644 index 6036631358..0000000000 --- a/.chronus/changes/fix-numeric-leading-zeros-2024-6-18-19-57-12.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix decimal numeric with leading zeros diff --git a/.chronus/changes/fix-openapi3-circular-ref-regression-2024-6-31-14-17-20.md b/.chronus/changes/fix-openapi3-circular-ref-regression-2024-6-31-14-17-20.md deleted file mode 100644 index 872ea1fd9b..0000000000 --- a/.chronus/changes/fix-openapi3-circular-ref-regression-2024-6-31-14-17-20.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/openapi3" ---- - diff --git a/.chronus/changes/fix-response-examples-2024-6-29-22-38-45.md b/.chronus/changes/fix-response-examples-2024-6-29-22-38-45.md deleted file mode 100644 index 5693cecb99..0000000000 --- a/.chronus/changes/fix-response-examples-2024-6-29-22-38-45.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix type comparison of literal and scalar when in projection context diff --git a/.chronus/changes/fix-response-examples-2024-6-30-15-26-28.md b/.chronus/changes/fix-response-examples-2024-6-30-15-26-28.md deleted file mode 100644 index 440741f71e..0000000000 --- a/.chronus/changes/fix-response-examples-2024-6-30-15-26-28.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fix issue where operation example would produce an empty object when `@body`/`@bodyRoot` was used diff --git a/.chronus/changes/fix-response-examples-2024-6-30-15-59-29.md b/.chronus/changes/fix-response-examples-2024-6-30-15-59-29.md deleted file mode 100644 index 33457d4cdc..0000000000 --- a/.chronus/changes/fix-response-examples-2024-6-30-15-59-29.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fix operation response body examples showing up for each response. diff --git a/.chronus/changes/fix-response-examples-2024-6-30-22-22-9.md b/.chronus/changes/fix-response-examples-2024-6-30-22-22-9.md deleted file mode 100644 index 559242ce36..0000000000 --- a/.chronus/changes/fix-response-examples-2024-6-30-22-22-9.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/http" ---- - -API: Expose `properties: HttpProperty[]` on operation parameter and response which reference all the properties of interest(Body, statusCode, contentType, implicitBodyProperty, etc.) diff --git a/.chronus/changes/fix-server-js-version-2024-6-24-10-1-25.md b/.chronus/changes/fix-server-js-version-2024-6-24-10-1-25.md deleted file mode 100644 index 7e3cfbd5d8..0000000000 --- a/.chronus/changes/fix-server-js-version-2024-6-24-10-1-25.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/http-server-javascript" ---- - diff --git a/.chronus/changes/fix-tsp-default-csv1-2024-7-7-14-31-14.md b/.chronus/changes/fix-tsp-default-csv1-2024-7-7-14-31-14.md deleted file mode 100644 index 29944196b6..0000000000 --- a/.chronus/changes/fix-tsp-default-csv1-2024-7-7-14-31-14.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/http" ---- - diff --git a/.chronus/changes/fix-uri-template-encode-reserved-char-2024-7-6-18-53-32.md b/.chronus/changes/fix-uri-template-encode-reserved-char-2024-7-6-18-53-32.md deleted file mode 100644 index 29944196b6..0000000000 --- a/.chronus/changes/fix-uri-template-encode-reserved-char-2024-7-6-18-53-32.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/http" ---- - diff --git a/.chronus/changes/inv-openapi3-circ-ref-2024-6-19-13-33-42.md b/.chronus/changes/inv-openapi3-circ-ref-2024-6-19-13-33-42.md deleted file mode 100644 index 2335ba3e71..0000000000 --- a/.chronus/changes/inv-openapi3-circ-ref-2024-6-19-13-33-42.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fixes bug where union documentation was being applied to each union member in emitted output. \ No newline at end of file diff --git a/.chronus/changes/json-schema-extension-values-2024-6-16-9-43-39.md b/.chronus/changes/json-schema-extension-values-2024-6-16-9-43-39.md deleted file mode 100644 index 411ac29e92..0000000000 --- a/.chronus/changes/json-schema-extension-values-2024-6-16-9-43-39.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -changeKind: breaking -packages: - - "@typespec/json-schema" ---- - -Updates `@extension` decorator to support TypeSpec values in addition to types. - -In previous versions of the json-schema emitter, the `@extension` decorator only accepted types as the value. These are emitted as JSON schemas. In order to add extensions as raw values, types had to be wrapped in the `Json<>` template when being passed to the `@extension` decorator. - -This change allows setting TypeSpec values (introduced in TypeSpec 0.57.0) directly instead. - -The following example demonstrates using values directly: - -```tsp -@extension("x-example", #{ foo: "bar" }) -model Foo {} -``` - -This change results in scalars being treated as values instead of types. This will result in the `@extension` decorator emitting raw values for scalar types instead of JSON schema. To preserve the previous behavior, use `typeof` when passing in a scalar value. - -The following example demonstrates how to pass a scalar value that emits a JSON schema: - -```tsp -@extension("x-example", "foo") -model Foo {} -``` - -To preserve this same behavior, the above example can be updated to the following: - -```tsp -@extension("x-example", typeof "foo") -model Foo {} -``` diff --git a/.chronus/changes/keep-watch-internal-compiler-error-2024-6-25-21-39-16.md b/.chronus/changes/keep-watch-internal-compiler-error-2024-6-25-21-39-16.md deleted file mode 100644 index eb93d0bcd3..0000000000 --- a/.chronus/changes/keep-watch-internal-compiler-error-2024-6-25-21-39-16.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -`tsp compile --watch` will not stop when a crash happens during compilation diff --git a/.chronus/changes/lib-const-2024-6-22-22-3-25.md b/.chronus/changes/lib-const-2024-6-22-22-3-25.md deleted file mode 100644 index c17edf07da..0000000000 --- a/.chronus/changes/lib-const-2024-6-22-22-3-25.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Add `const` template parameter to get the precise lib type diff --git a/.chronus/changes/lib-const-2024-6-22-22-3-26.md b/.chronus/changes/lib-const-2024-6-22-22-3-26.md deleted file mode 100644 index e6c475b297..0000000000 --- a/.chronus/changes/lib-const-2024-6-22-22-3-26.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/http-server-javascript" - - "@typespec/http" - - "@typespec/protobuf" ---- - -Fix some diagnostic not showing the right message diff --git a/.chronus/changes/mk-set-root-extensions-2024-6-18-19-20-36.md b/.chronus/changes/mk-set-root-extensions-2024-6-18-19-20-36.md deleted file mode 100644 index ec9e55ff3d..0000000000 --- a/.chronus/changes/mk-set-root-extensions-2024-6-18-19-20-36.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: feature -packages: - - "@typespec/openapi3" ---- - -`@extension` used on the service namespace will set extension at the root of the document \ No newline at end of file diff --git a/.chronus/changes/openapi3-fix-circ-ref-unions-2024-6-19-10-0-54.md b/.chronus/changes/openapi3-fix-circ-ref-unions-2024-6-19-10-0-54.md deleted file mode 100644 index 2d5d19ad2a..0000000000 --- a/.chronus/changes/openapi3-fix-circ-ref-unions-2024-6-19-10-0-54.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fixes bug where circular references in unions caused an empty object to be emitted instead of a ref. \ No newline at end of file diff --git a/.chronus/changes/path-unix-style-2024-6-25-15-13-16.md b/.chronus/changes/path-unix-style-2024-6-25-15-13-16.md deleted file mode 100644 index ab5446159c..0000000000 --- a/.chronus/changes/path-unix-style-2024-6-25-15-13-16.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Warn when using `\` in config file field that expect a path. \ No newline at end of file diff --git a/.chronus/changes/refactor-shared-routes-2024-6-29-19-52-22.md b/.chronus/changes/refactor-shared-routes-2024-6-29-19-52-22.md deleted file mode 100644 index df322697fa..0000000000 --- a/.chronus/changes/refactor-shared-routes-2024-6-29-19-52-22.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/openapi3" ---- - -Refactor openapi3 shared route to reuse logic better diff --git a/.chronus/changes/service-csharp-2024-1-12-3-50-33.md b/.chronus/changes/service-csharp-2024-1-12-3-50-33.md deleted file mode 100644 index a9f2df452a..0000000000 --- a/.chronus/changes/service-csharp-2024-1-12-3-50-33.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/http-server-csharp" ---- - -Initial check-in for CSharp service emitter diff --git a/.chronus/changes/tspd-generate-interface-sigs-2024-6-19-15-34-36.md b/.chronus/changes/tspd-generate-interface-sigs-2024-6-19-15-34-36.md deleted file mode 100644 index c97ed69d5a..0000000000 --- a/.chronus/changes/tspd-generate-interface-sigs-2024-6-19-15-34-36.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/compiler" - - "@typespec/http" ---- - -Tspd generate interface for valueof models used in decorators diff --git a/.chronus/changes/upgrade-deps-july-2024-2-2024-6-22-23-39-34.md b/.chronus/changes/upgrade-deps-july-2024-2-2024-6-22-23-39-34.md deleted file mode 100644 index a59a73c68e..0000000000 --- a/.chronus/changes/upgrade-deps-july-2024-2-2024-6-22-23-39-34.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: dependencies -packages: - - "@typespec/bundler" - - "@typespec/compiler" - - "@typespec/eslint-plugin" - - "@typespec/html-program-viewer" - - "@typespec/http-server-javascript" - - "@typespec/http" - - "@typespec/internal-build-utils" - - "@typespec/json-schema" - - "@typespec/library-linter" - - "@typespec/openapi" - - "@typespec/openapi3" - - "@typespec/playground" - - "@typespec/prettier-plugin-typespec" - - "@typespec/protobuf" - - "@typespec/rest" - - tmlanguage-generator - - typespec-vscode - - "@typespec/versioning" - - "@typespec/xml" ---- - -Update dependencies diff --git a/.chronus/changes/uri-templates-2024-6-24-20-7-39.md b/.chronus/changes/uri-templates-2024-6-24-20-7-39.md deleted file mode 100644 index 5b7e4db705..0000000000 --- a/.chronus/changes/uri-templates-2024-6-24-20-7-39.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/http" ---- - -`@route` can now take a uri template as defined by [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) - - ```tsp - @route("files{+path}") download(path: string): void; - ``` diff --git a/.chronus/changes/uri-templates-2024-6-24-21-37-52.md b/.chronus/changes/uri-templates-2024-6-24-21-37-52.md deleted file mode 100644 index ff5c021cf0..0000000000 --- a/.chronus/changes/uri-templates-2024-6-24-21-37-52.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/openapi3" - - "@typespec/rest" ---- - -Add support for URI templates in routes diff --git a/.chronus/changes/uri-templates-2024-6-25-9-3-39-2.md b/.chronus/changes/uri-templates-2024-6-25-9-3-39-2.md deleted file mode 100644 index fb4b55465d..0000000000 --- a/.chronus/changes/uri-templates-2024-6-25-9-3-39-2.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: deprecation -packages: - - "@typespec/http" ---- - -API deprecation: `HttpOperation#pathSegments` is deprecated. Use `HttpOperation#uriTemplate` instead. diff --git a/.chronus/changes/uri-templates-2024-6-25-9-3-39.md b/.chronus/changes/uri-templates-2024-6-25-9-3-39.md deleted file mode 100644 index 88324b314b..0000000000 --- a/.chronus/changes/uri-templates-2024-6-25-9-3-39.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -changeKind: deprecation -packages: - - "@typespec/http" ---- - -Deprecated `@query({format: })` option. Use `@query(#{explode: true})` instead of `form` or `multi` format. Previously `csv`/`simple` is the default now. - Decorator is also expecting an object value now instead of a model. A deprecation warning with a codefix will help migrating. - - ```diff - - @query({format: "form"}) select: string[]; - + @query(#{explode: true}) select: string[]; - ``` diff --git a/.chronus/changes/uri-templates-2024-7-6-16-39-59.md b/.chronus/changes/uri-templates-2024-7-6-16-39-59.md deleted file mode 100644 index 35c362b3ba..0000000000 --- a/.chronus/changes/uri-templates-2024-7-6-16-39-59.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Add `ArrayEncoding` enum to define simple serialization of arrays diff --git a/.chronus/changes/witemple-msft-hsj-petstore-fixes-2024-7-6-16-28-8.md b/.chronus/changes/witemple-msft-hsj-petstore-fixes-2024-7-6-16-28-8.md deleted file mode 100644 index 70acc9995a..0000000000 --- a/.chronus/changes/witemple-msft-hsj-petstore-fixes-2024-7-6-16-28-8.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/http-server-javascript" ---- - -Fixed enum representation, an edge case with optional parameter joining, and a couple of type errors around query/header params. \ No newline at end of file diff --git a/.chronus/changes/witemple-msft-hsj-router-param-bug-2024-7-7-15-20-46.md b/.chronus/changes/witemple-msft-hsj-router-param-bug-2024-7-7-15-20-46.md deleted file mode 100644 index e6b2d73577..0000000000 --- a/.chronus/changes/witemple-msft-hsj-router-param-bug-2024-7-7-15-20-46.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -changeKind: fix -packages: - - typespec-vs - - "@typespec/http-server-javascript" ---- - -Fixed a router bug where paths would sometimes fail to match after a parameter was bound. \ No newline at end of file diff --git a/packages/bundler/CHANGELOG.md b/packages/bundler/CHANGELOG.md index 3159ff0004..13dbbc004a 100644 --- a/packages/bundler/CHANGELOG.md +++ b/packages/bundler/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/bundler +## 0.1.6 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.1.5 ### Bump dependencies diff --git a/packages/bundler/package.json b/packages/bundler/package.json index 3bac7af20e..23a9dda835 100644 --- a/packages/bundler/package.json +++ b/packages/bundler/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/bundler", - "version": "0.1.5", + "version": "0.1.6", "author": "Microsoft Corporation", "description": "Package to bundle a TypeSpec library.", "homepage": "https://typespec.io", diff --git a/packages/compiler/CHANGELOG.md b/packages/compiler/CHANGELOG.md index 4234b42d00..c42181e827 100644 --- a/packages/compiler/CHANGELOG.md +++ b/packages/compiler/CHANGELOG.md @@ -1,5 +1,74 @@ # Change Log - @typespec/compiler +## 0.59.0 + +### Bug Fixes + +- [#3881](https://github.com/microsoft/typespec/pull/3881) Fixes a bug where ending a non-terminal line in a multi-line comment with a backslash caused the next star to show up in the parsed doc string. +- [#4050](https://github.com/microsoft/typespec/pull/4050) Allow using compact namespace form `Foo.Bar` when inside another namespace + ```tsp + namespace MyOrg.MyProject { + namespace MyModule.MySubmodule { // <-- this used to emit an error + // ... + } + } + ``` +- [#3898](https://github.com/microsoft/typespec/pull/3898) Fix decimal numeric with leading zeros +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix type comparison of literal and scalar when in projection context +- [#4022](https://github.com/microsoft/typespec/pull/4022) `tsp compile --watch` will not stop when a crash happens during compilation +- [#3933](https://github.com/microsoft/typespec/pull/3933) Add `const` template parameter to get the precise lib type + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Features + +- [#3906](https://github.com/microsoft/typespec/pull/3906) Support completion for template parameter extending model or object value + + Example + ```tsp + model User { + } + alias user = User< {┆ + | [age] + | [name] + ``` +- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string +- [#4023](https://github.com/microsoft/typespec/pull/4023) Warn when using `\` in config file field that expect a path. +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add `ArrayEncoding` enum to define simple serialization of arrays + +### Breaking Changes + +- [#4050](https://github.com/microsoft/typespec/pull/4050) Fix issue where naming a namespace with the same name as the blockless namespace would merge with it instead of creating a subnamespace like any other name would. + + ```tsp + namespace MyOrg.MyProject; + + namespace MyOrg.MyProject.MyArea { + model A {} + } + + namespace MyArea2 { + model B {} + } + ``` + + Previously model `A` would end-up in namespace `MyOrg.MyProject.MyArea` and model `B` in `MyOrg.MyProject.MyArea2`. With this change model `A` will now be in `MyOrg.MyProject.MyOrg.MyProject.MyArea`. To achieve the previous behavior the above code should be written as: + + ```tsp + namespace MyOrg.MyProject; + + namespace MyArea { + model A {} + } + + namespace MyArea2 { + model B {} + } + ``` + + ## 0.58.1 ### Bug Fixes diff --git a/packages/compiler/package.json b/packages/compiler/package.json index ab25773522..1ee216e4ba 100644 --- a/packages/compiler/package.json +++ b/packages/compiler/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/compiler", - "version": "0.58.1", + "version": "0.59.0", "description": "TypeSpec Compiler Preview", "author": "Microsoft Corporation", "license": "MIT", diff --git a/packages/compiler/templates/scaffolding.json b/packages/compiler/templates/scaffolding.json index 29e8d78e5a..648cd92db5 100644 --- a/packages/compiler/templates/scaffolding.json +++ b/packages/compiler/templates/scaffolding.json @@ -3,12 +3,12 @@ "title": "Empty project", "description": "Create an empty project.", "libraries": [], - "compilerVersion": "0.58.1" + "compilerVersion": "0.59.0" }, "rest": { "title": "Generic REST API", "description": "Create a project representing a generic REST API", - "compilerVersion": "0.58.1", + "compilerVersion": "0.59.0", "libraries": [ "@typespec/http", "@typespec/rest", @@ -23,7 +23,7 @@ "library-ts": { "title": "TypeSpec Library (With TypeScript)", "description": "Create a new package to add decorators or linters to typespec.", - "compilerVersion": "0.58.1", + "compilerVersion": "0.59.0", "libraries": [], "files": [ { @@ -99,7 +99,7 @@ "emitter-ts": { "title": "TypeSpec Emitter (With TypeScript)", "description": "Create a new package that will be emitting typespec", - "compilerVersion": "0.58.1", + "compilerVersion": "0.59.0", "libraries": [], "files": [ { diff --git a/packages/eslint-plugin-typespec/CHANGELOG.md b/packages/eslint-plugin-typespec/CHANGELOG.md index 96c820c8ae..8767d6511f 100644 --- a/packages/eslint-plugin-typespec/CHANGELOG.md +++ b/packages/eslint-plugin-typespec/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/eslint-plugin +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/eslint-plugin-typespec/package.json b/packages/eslint-plugin-typespec/package.json index f0ad536268..dd4bd403b9 100644 --- a/packages/eslint-plugin-typespec/package.json +++ b/packages/eslint-plugin-typespec/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/eslint-plugin", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "Eslint plugin providing set of rules to be used in the JS/TS code of TypeSpec libraries", "homepage": "https://typespec.io", diff --git a/packages/html-program-viewer/CHANGELOG.md b/packages/html-program-viewer/CHANGELOG.md index 15f5dfcd90..90525262c0 100644 --- a/packages/html-program-viewer/CHANGELOG.md +++ b/packages/html-program-viewer/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/html-program-viewer +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bug Fixes diff --git a/packages/html-program-viewer/package.json b/packages/html-program-viewer/package.json index 5ac0e97399..e587f0ccb2 100644 --- a/packages/html-program-viewer/package.json +++ b/packages/html-program-viewer/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/html-program-viewer", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library for emitting an html view of the program.", "homepage": "https://typespec.io", diff --git a/packages/http-server-csharp/CHANGELOG.md b/packages/http-server-csharp/CHANGELOG.md index 6867f0bf58..3e2f073da4 100644 --- a/packages/http-server-csharp/CHANGELOG.md +++ b/packages/http-server-csharp/CHANGELOG.md @@ -1,2 +1,6 @@ # Change Log - @typespec/http-server-csharp +## 0.58.0-alpha.2 + +No changes, version bump only. + diff --git a/packages/http-server-csharp/package.json b/packages/http-server-csharp/package.json index eb7579cfc5..dd19fc20cc 100644 --- a/packages/http-server-csharp/package.json +++ b/packages/http-server-csharp/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/http-server-csharp", - "version": "0.58.0-alpha.1", + "version": "0.58.0-alpha.2", "author": "Microsoft Corporation", "description": "TypeSpec service code generator for c-sharp", "homepage": "https://typespec.io", diff --git a/packages/http-server-javascript/CHANGELOG.md b/packages/http-server-javascript/CHANGELOG.md index a5f57a73ae..00c90b8c64 100644 --- a/packages/http-server-javascript/CHANGELOG.md +++ b/packages/http-server-javascript/CHANGELOG.md @@ -1,3 +1,16 @@ # Changelog - @typespec/http-server-javascript +## 0.58.0-alpha.2 + +### Bug Fixes + +- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message +- [#4101](https://github.com/microsoft/typespec/pull/4101) Fixed enum representation, an edge case with optional parameter joining, and a couple of type errors around query/header params. +- [#4115](https://github.com/microsoft/typespec/pull/4115) Fixed a router bug where paths would sometimes fail to match after a parameter was bound. + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + diff --git a/packages/http-server-javascript/package.json b/packages/http-server-javascript/package.json index 04585f15ff..0931baf3c2 100644 --- a/packages/http-server-javascript/package.json +++ b/packages/http-server-javascript/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/http-server-javascript", - "version": "0.58.0-alpha.1", + "version": "0.58.0-alpha.2", "author": "Microsoft Corporation", "description": "TypeSpec HTTP server code generator for JavaScript", "homepage": "https://github.com/microsoft/typespec", diff --git a/packages/http/CHANGELOG.md b/packages/http/CHANGELOG.md index a9b6284ae1..c967b032d3 100644 --- a/packages/http/CHANGELOG.md +++ b/packages/http/CHANGELOG.md @@ -1,5 +1,37 @@ # Change Log - @typespec/http +## 0.59.0 + +### Bug Fixes + +- [#3909](https://github.com/microsoft/typespec/pull/3909) Fix `HttpPart` not respecting explicit part name by always using the property name +- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Features + +- [#4046](https://github.com/microsoft/typespec/pull/4046) API: Expose `properties: HttpProperty[]` on operation parameter and response which reference all the properties of interest(Body, statusCode, contentType, implicitBodyProperty, etc.) +- [#3932](https://github.com/microsoft/typespec/pull/3932) `@route` can now take a uri template as defined by [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) + + ```tsp + @route("files{+path}") download(path: string): void; + ``` + +### Deprecations + +- [#3932](https://github.com/microsoft/typespec/pull/3932) API deprecation: `HttpOperation#pathSegments` is deprecated. Use `HttpOperation#uriTemplate` instead. +- [#3932](https://github.com/microsoft/typespec/pull/3932) Deprecated `@query({format: })` option. Use `@query(#{explode: true})` instead of `form` or `multi` format. Previously `csv`/`simple` is the default now. + Decorator is also expecting an object value now instead of a model. A deprecation warning with a codefix will help migrating. + + ```diff + - @query({format: "form"}) select: string[]; + + @query(#{explode: true}) select: string[]; + ``` + + ## 0.58.0 ### Bump dependencies diff --git a/packages/http/package.json b/packages/http/package.json index 9993260466..0f9172773c 100644 --- a/packages/http/package.json +++ b/packages/http/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/http", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec HTTP protocol binding", "homepage": "https://github.com/microsoft/typespec", diff --git a/packages/internal-build-utils/CHANGELOG.md b/packages/internal-build-utils/CHANGELOG.md index eb103cecbd..775c5915d1 100644 --- a/packages/internal-build-utils/CHANGELOG.md +++ b/packages/internal-build-utils/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/internal-build-utils +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/internal-build-utils/package.json b/packages/internal-build-utils/package.json index 5c8156183b..0e618fafc1 100644 --- a/packages/internal-build-utils/package.json +++ b/packages/internal-build-utils/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/internal-build-utils", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "Internal library to TypeSpec providing helpers to build.", "homepage": "https://typespec.io", diff --git a/packages/json-schema/CHANGELOG.md b/packages/json-schema/CHANGELOG.md index 342dc93452..047c9e0972 100644 --- a/packages/json-schema/CHANGELOG.md +++ b/packages/json-schema/CHANGELOG.md @@ -1,5 +1,43 @@ # Change Log - @typespec/json-schema +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Breaking Changes + +- [#3558](https://github.com/microsoft/typespec/pull/3558) Updates `@extension` decorator to support TypeSpec values in addition to types. + +In previous versions of the json-schema emitter, the `@extension` decorator only accepted types as the value. These are emitted as JSON schemas. In order to add extensions as raw values, types had to be wrapped in the `Json<>` template when being passed to the `@extension` decorator. + +This change allows setting TypeSpec values (introduced in TypeSpec 0.57.0) directly instead. + +The following example demonstrates using values directly: + +```tsp +@extension("x-example", #{ foo: "bar" }) +model Foo {} +``` + +This change results in scalars being treated as values instead of types. This will result in the `@extension` decorator emitting raw values for scalar types instead of JSON schema. To preserve the previous behavior, use `typeof` when passing in a scalar value. + +The following example demonstrates how to pass a scalar value that emits a JSON schema: + +```tsp +@extension("x-example", "foo") +model Foo {} +``` + +To preserve this same behavior, the above example can be updated to the following: + +```tsp +@extension("x-example", typeof "foo") +model Foo {} +``` + + ## 0.58.0 ### Bug Fixes diff --git a/packages/json-schema/package.json b/packages/json-schema/package.json index b3655eff80..f22a278ef1 100644 --- a/packages/json-schema/package.json +++ b/packages/json-schema/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/json-schema", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec", "homepage": "https://github.com/microsoft/typespec", diff --git a/packages/library-linter/CHANGELOG.md b/packages/library-linter/CHANGELOG.md index be732ef005..4be7777000 100644 --- a/packages/library-linter/CHANGELOG.md +++ b/packages/library-linter/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/library-linter +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/library-linter/package.json b/packages/library-linter/package.json index a71bb61985..7b4f779c25 100644 --- a/packages/library-linter/package.json +++ b/packages/library-linter/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/library-linter", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library for linting another library.", "homepage": "https://typespec.io", diff --git a/packages/openapi/CHANGELOG.md b/packages/openapi/CHANGELOG.md index ba3e935be3..ed50e1951b 100644 --- a/packages/openapi/CHANGELOG.md +++ b/packages/openapi/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/openapi +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/openapi/package.json b/packages/openapi/package.json index 8d953938b7..932ebb8261 100644 --- a/packages/openapi/package.json +++ b/packages/openapi/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/openapi", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library providing OpenAPI concepts", "homepage": "https://typespec.io", diff --git a/packages/openapi3/CHANGELOG.md b/packages/openapi3/CHANGELOG.md index 7c6000c11c..6847ca3535 100644 --- a/packages/openapi3/CHANGELOG.md +++ b/packages/openapi3/CHANGELOG.md @@ -1,5 +1,26 @@ # Change Log - @typespec/openapi3 +## 0.59.0 + +### Bug Fixes + +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix issue where operation example would produce an empty object when `@body`/`@bodyRoot` was used +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix operation response body examples showing up for each response. +- [#3912](https://github.com/microsoft/typespec/pull/3912) Fixes bug where union documentation was being applied to each union member in emitted output. +- [#3908](https://github.com/microsoft/typespec/pull/3908) Fixes bug where circular references in unions caused an empty object to be emitted instead of a ref. + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Features + +- [#3894](https://github.com/microsoft/typespec/pull/3894) Add support for `@useRef` on responses +- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string +- [#3890](https://github.com/microsoft/typespec/pull/3890) `@extension` used on the service namespace will set extension at the root of the document +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes + + ## 0.58.0 ### Bug Fixes diff --git a/packages/openapi3/package.json b/packages/openapi3/package.json index 9f9ac76c42..cda7bfc04a 100644 --- a/packages/openapi3/package.json +++ b/packages/openapi3/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/openapi3", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec", "homepage": "https://typespec.io", diff --git a/packages/playground/CHANGELOG.md b/packages/playground/CHANGELOG.md index 2dbb422c06..ffe08c8ffb 100644 --- a/packages/playground/CHANGELOG.md +++ b/packages/playground/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/playground +## 0.4.1 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.4.0 ### Bump dependencies diff --git a/packages/playground/package.json b/packages/playground/package.json index b823da7f35..3c0c1a523d 100644 --- a/packages/playground/package.json +++ b/packages/playground/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/playground", - "version": "0.4.0", + "version": "0.4.1", "author": "Microsoft Corporation", "description": "TypeSpec playground UI components.", "homepage": "https://typespec.io", diff --git a/packages/prettier-plugin-typespec/CHANGELOG.md b/packages/prettier-plugin-typespec/CHANGELOG.md index 2681761829..93ee055cea 100644 --- a/packages/prettier-plugin-typespec/CHANGELOG.md +++ b/packages/prettier-plugin-typespec/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/prettier-plugin-typespec +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/prettier-plugin-typespec/package.json b/packages/prettier-plugin-typespec/package.json index e4bd19d0b5..b2ef88f5b8 100644 --- a/packages/prettier-plugin-typespec/package.json +++ b/packages/prettier-plugin-typespec/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/prettier-plugin-typespec", - "version": "0.58.0", + "version": "0.59.0", "description": "", "main": "dist/index.js", "scripts": { diff --git a/packages/protobuf/CHANGELOG.md b/packages/protobuf/CHANGELOG.md index 6a84cc91d1..a4f5fa1b29 100644 --- a/packages/protobuf/CHANGELOG.md +++ b/packages/protobuf/CHANGELOG.md @@ -1,5 +1,16 @@ # Change Log - @typespec/protobuf +## 0.59.0 + +### Bug Fixes + +- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/protobuf/package.json b/packages/protobuf/package.json index 4ecab96da9..f0d200fe8a 100644 --- a/packages/protobuf/package.json +++ b/packages/protobuf/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/protobuf", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library and emitter for Protobuf (gRPC)", "homepage": "https://github.com/microsoft/typespec", diff --git a/packages/rest/CHANGELOG.md b/packages/rest/CHANGELOG.md index fb8fcf7ae5..3f1e55fdea 100644 --- a/packages/rest/CHANGELOG.md +++ b/packages/rest/CHANGELOG.md @@ -1,5 +1,16 @@ # Change Log - @typespec/rest +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Features + +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes + + ## 0.58.0 ### Bump dependencies diff --git a/packages/rest/package.json b/packages/rest/package.json index 139d4e5134..7336b0a079 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/rest", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec REST protocol binding", "homepage": "https://typespec.io", diff --git a/packages/tmlanguage-generator/CHANGELOG.md b/packages/tmlanguage-generator/CHANGELOG.md index 85ba870586..64dccf1980 100644 --- a/packages/tmlanguage-generator/CHANGELOG.md +++ b/packages/tmlanguage-generator/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - tmlanguage-generator +## 0.5.8 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.5.7 ### Bump dependencies diff --git a/packages/tmlanguage-generator/package.json b/packages/tmlanguage-generator/package.json index a70811c606..6c3d0d0126 100644 --- a/packages/tmlanguage-generator/package.json +++ b/packages/tmlanguage-generator/package.json @@ -1,6 +1,6 @@ { "name": "tmlanguage-generator", - "version": "0.5.7", + "version": "0.5.8", "author": "Microsoft Corporation", "description": "Helper library to generate TextMate syntax highlighting tmLanguage files.", "homepage": "https://github.com/microsoft/typespec/tree/main/packages/tmlanguage-generator", diff --git a/packages/typespec-vs/CHANGELOG.md b/packages/typespec-vs/CHANGELOG.md index 45301e9977..c0eb5932e3 100644 --- a/packages/typespec-vs/CHANGELOG.md +++ b/packages/typespec-vs/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - typespec-vs +## 0.59.0 + +### Bug Fixes + +- [#4115](https://github.com/microsoft/typespec/pull/4115) Fixed a router bug where paths would sometimes fail to match after a parameter was bound. + + ## 0.58.0 No changes, version bump only. diff --git a/packages/typespec-vs/package.json b/packages/typespec-vs/package.json index 55616c6b6d..3f40aad45d 100644 --- a/packages/typespec-vs/package.json +++ b/packages/typespec-vs/package.json @@ -1,7 +1,7 @@ { "name": "typespec-vs", "author": "Microsoft Corporation", - "version": "0.58.0", + "version": "0.59.0", "description": "TypeSpec Language Support for Visual Studio", "homepage": "https://typespec.io", "readme": "https://github.com/microsoft/typespec/blob/main/README.md", diff --git a/packages/typespec-vscode/CHANGELOG.md b/packages/typespec-vscode/CHANGELOG.md index 898c6395b2..6660c204ed 100644 --- a/packages/typespec-vscode/CHANGELOG.md +++ b/packages/typespec-vscode/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - typespec-vscode +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/typespec-vscode/package.json b/packages/typespec-vscode/package.json index b48f5818d0..0d15c964f2 100644 --- a/packages/typespec-vscode/package.json +++ b/packages/typespec-vscode/package.json @@ -1,6 +1,6 @@ { "name": "typespec-vscode", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec language support for VS Code", "homepage": "https://typespec.io", diff --git a/packages/versioning/CHANGELOG.md b/packages/versioning/CHANGELOG.md index 16b3b82de1..c5a7c13769 100644 --- a/packages/versioning/CHANGELOG.md +++ b/packages/versioning/CHANGELOG.md @@ -1,5 +1,17 @@ # Change Log - @typespec/versioning +## 0.59.0 + +### Bug Fixes + +- [#3911](https://github.com/microsoft/typespec/pull/3911) Allow spreading a model that has props added in previous version +- [#3951](https://github.com/microsoft/typespec/pull/3951) Fixes issue where spreading a versioned model as a parameter to an incompatible versioned operation would cause the compiler to crash. + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + + ## 0.58.0 ### Bump dependencies diff --git a/packages/versioning/package.json b/packages/versioning/package.json index e12b778a6f..9768b35b09 100644 --- a/packages/versioning/package.json +++ b/packages/versioning/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/versioning", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library for declaring and emitting versioned APIs", "homepage": "https://typespec.io", diff --git a/packages/website/playground-versions.json b/packages/website/playground-versions.json index d698e10484..e7f24cd81f 100644 --- a/packages/website/playground-versions.json +++ b/packages/website/playground-versions.json @@ -1,4 +1,5 @@ [ + "0.59.x", "0.58.x", "0.57.x", "0.56.x", diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/data-types.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/data-types.md index 845b3e54b8..00d426ca02 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/data-types.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/data-types.md @@ -36,3 +36,24 @@ Well-known JSON Schema formats. ```typespec enum TypeSpec.JsonSchema.Format ``` + +| Name | Value | Description | +| ------------------- | ------------------------- | ----------- | +| dateTime | `"date-time"` | | +| date | `"date"` | | +| time | `"time"` | | +| duration | `"duration"` | | +| email | `"email"` | | +| idnEmail | `"idn-email"` | | +| hostname | `"hostname"` | | +| idnHostname | `"idn-hostname"` | | +| ipv4 | `"ipv4"` | | +| ipv6 | `"ipv6"` | | +| uri | `"uri"` | | +| uriReference | `"uri-reference"` | | +| iri | `"iri"` | | +| iriReference | `"iri-reference"` | | +| uuid | `"uuid"` | | +| jsonPointer | `"json-pointer"` | | +| relativeJsonPointer | `"relative-json-pointer"` | | +| regex | `"regex"` | | diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/decorators.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/decorators.md index e8445e5ad4..2d7f756e48 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/decorators.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/decorators.md @@ -103,13 +103,23 @@ media type and encoding. ### `@extension` {#@TypeSpec.JsonSchema.extension} Specify a custom property to add to the emitted schema. Useful for adding custom keywords -and other vendor-specific extensions. The value will be converted to a schema unless the parameter -is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will -emit a JSON schema value for `x-schema`, whereas `@extension("x-schema", Json<{x: "value"}>)` will -emit the raw JSON code `{x: "value"}`. +and other vendor-specific extensions. Scalar values need to be specified using `typeof` to be converted to a schema. + +For example, `@extension("x-schema", typeof "foo")` will emit a JSON schema value for `x-schema`, +whereas `@extension("x-schema", "foo")` will emit the raw code `"foo"`. + +The value will be treated as a raw value if any of the following are true: + +1. The value is a scalar value (e.g. string, number, boolean, etc.) +2. The value is wrapped in the `Json` template +3. The value is provided using the value syntax (e.g. `#{}`, `#[]`) + +For example, `@extension("x-schema", { x: "value" })` will emit a JSON schema value for `x-schema`, +whereas `@extension("x-schema", #{x: "value"})` and `@extension("x-schema", Json<{x: "value"}>)` +will emit the raw JSON code `{x: "value"}`. ```typespec -@TypeSpec.JsonSchema.extension(key: valueof string, value: unknown) +@TypeSpec.JsonSchema.extension(key: valueof string, value: unknown | valueof unknown) ``` #### Target @@ -118,10 +128,10 @@ emit the raw JSON code `{x: "value"}`. #### Parameters -| Name | Type | Description | -| ----- | ---------------- | --------------------------------------------------------------------------------------- | -| key | `valueof string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| Name | Type | Description | +| ----- | ------------------------------ | ------------------------------------------------------------- | +| key | `valueof string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `unknown` \| `valueof unknown` | the value of the keyword. | ### `@id` {#@TypeSpec.JsonSchema.id} diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/$extension.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/$extension.md index 90e0f4e1b1..72ce216a5c 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/$extension.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/$extension.md @@ -18,7 +18,7 @@ function $extension( | `context` | `DecoratorContext` | | `target` | `Type` | | `key` | `string` | -| `value` | `Type` | +| `value` | `unknown` | ## Returns diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/setExtension.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/setExtension.md new file mode 100644 index 0000000000..aa806cfd62 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/functions/setExtension.md @@ -0,0 +1,25 @@ +--- +jsApi: true +title: "[F] setExtension" + +--- +```ts +function setExtension( + program, + target, + key, + value): void +``` + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `program` | `Program` | +| `target` | `Type` | +| `key` | `string` | +| `value` | `unknown` | + +## Returns + +`void` diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/index.md index bbaab5b47d..a1064819a3 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/index.md @@ -63,3 +63,4 @@ title: "[P] JS API" - [getUniqueItems](functions/getUniqueItems.md) - [isJsonSchemaDeclaration](functions/isJsonSchemaDeclaration.md) - [isOneOf](functions/isOneOf.md) +- [setExtension](functions/setExtension.md) diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/interfaces/ExtensionRecord.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/interfaces/ExtensionRecord.md index fc3d076fa0..983f28c070 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/interfaces/ExtensionRecord.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/interfaces/ExtensionRecord.md @@ -8,4 +8,4 @@ title: "[I] ExtensionRecord" | Property | Type | | ------ | ------ | | `key` | `string` | -| `value` | `Type` | +| `value` | `unknown` | diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/$lib.md index 9950627c7c..99db26aa39 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/$lib.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/$lib.md @@ -12,8 +12,8 @@ const $lib: TypeSpecLibrary; | Name | Type | | ------ | ------ | | `duplicate-id` | `object` | -| `duplicate-id.default` | `CallableMessage`<[`string`]\> | +| `duplicate-id.default` | `CallableMessage`<[`"id"`]\> | | `invalid-default` | `object` | -| `invalid-default.default` | `CallableMessage`<[`string`]\> | +| `invalid-default.default` | `CallableMessage`<[`"type"`]\> | | `unknown-scalar` | `object` | -| `unknown-scalar.default` | `CallableMessage`<[`string`]\> | +| `unknown-scalar.default` | `CallableMessage`<[`"name"`]\> | diff --git a/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/js-api/variables/$lib.md index 79a6dc3b5a..cbe951f393 100644 --- a/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/js-api/variables/$lib.md +++ b/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/js-api/variables/$lib.md @@ -33,10 +33,14 @@ const $lib: TypeSpecLibrary; | `invalid-schema.default` | `CallableMessage`<[`"type"`]\> | - | | `invalid-server-variable` | `object` | - | | `invalid-server-variable.default` | `CallableMessage`<[`"propName"`]\> | - | +| `invalid-style` | `object` | - | +| `invalid-style.default` | `CallableMessage`<[`"style"`, `"paramType"`]\> | - | | `oneof-union` | `object` | - | | `oneof-union.default` | `"@oneOf decorator can only be used on a union or a model property which type is a union."` | "@oneOf decorator can only be used on a union or a model property which type is a union." | | `path-query` | `object` | - | | `path-query.default` | `"OpenAPI does not allow paths containing a query string."` | - | +| `path-reserved-expansion` | `object` | - | +| `path-reserved-expansion.default` | `"Reserved expansion of path parameter with '+' operator #{allowReserved: true} is not supported in OpenAPI3."` | - | | `resource-namespace` | `object` | - | | `resource-namespace.default` | `"Resource goes on namespace"` | "Resource goes on namespace" | | `status-code-in-default-response` | `object` | - | diff --git a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/data-types.md b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/data-types.md index 846a8b5c55..1888cdb2e2 100644 --- a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/data-types.md +++ b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/data-types.md @@ -99,6 +99,13 @@ See the [`@stream`](./decorators# enum TypeSpec.Protobuf.StreamMode ``` +| Name | Value | Description | +| ------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Duplex | | Both the input and output of the operation are streaming. Both the client and service will stream messages to each
other until the connections are closed. | +| In | | The input of the operation is streaming. The client will send a stream of events; and, once the stream is closed,
the service will respond with a message. | +| Out | | The output of the operation is streaming. The client will send a message to the service, and the service will send
a stream of events back to the client. | +| None | | Neither the input nor the output are streaming. This is the default mode of an operation without the `@stream`
decorator. | + ### `fixed32` {#TypeSpec.Protobuf.fixed32} An unsigned 32-bit integer that will use the `fixed32` encoding when used in a Protobuf message. diff --git a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$field.md b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$field.md index 7ba279c598..dae00def1e 100644 --- a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$field.md +++ b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$field.md @@ -10,6 +10,8 @@ function $field( index): void ``` +Decorate a model property with a field index. Field indices are required for all fields of emitted messages. + ## Parameters | Parameter | Type | Description | diff --git a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/variables/$lib.md index fddb2046c4..d1a920458e 100644 --- a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/variables/$lib.md +++ b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/variables/$lib.md @@ -12,46 +12,46 @@ const $lib: TypeSpecLibrary = TypeSpecPro | Name | Type | Default value | | ------ | ------ | ------ | | `anonymous-model` | `object` | - | -| `anonymous-model.default` | `string` | "anonymous models cannot be used in Protobuf messages" | +| `anonymous-model.default` | `"anonymous models cannot be used in Protobuf messages"` | "anonymous models cannot be used in Protobuf messages" | | `field-index` | `object` | - | -| `field-index.invalid` | `CallableMessage`<[`string`]\> | - | -| `field-index.missing` | `CallableMessage`<[`string`]\> | - | -| `field-index.out-of-bounds` | `CallableMessage`<[`string`, `string`]\> | - | -| `field-index.reserved` | `CallableMessage`<[`string`]\> | - | -| `field-index.user-reserved` | `CallableMessage`<[`string`]\> | - | -| `field-index.user-reserved-range` | `CallableMessage`<[`string`]\> | - | +| `field-index.invalid` | `CallableMessage`<[`"index"`]\> | - | +| `field-index.missing` | `CallableMessage`<[`"name"`]\> | - | +| `field-index.out-of-bounds` | `CallableMessage`<[`"index"`, `"max"`]\> | - | +| `field-index.reserved` | `CallableMessage`<[`"index"`]\> | - | +| `field-index.user-reserved` | `CallableMessage`<[`"index"`]\> | - | +| `field-index.user-reserved-range` | `CallableMessage`<[`"index"`]\> | - | | `field-name` | `object` | - | -| `field-name.user-reserved` | `CallableMessage`<[`string`]\> | - | +| `field-name.user-reserved` | `CallableMessage`<[`"name"`]\> | - | | `illegal-reservation` | `object` | - | -| `illegal-reservation.default` | `string` | "reservation value must be a string literal, uint32 literal, or a tuple of two uint32 literals denoting a range" | +| `illegal-reservation.default` | `"reservation value must be a string literal, uint32 literal, or a tuple of two uint32 literals denoting a range"` | "reservation value must be a string literal, uint32 literal, or a tuple of two uint32 literals denoting a range" | | `invalid-package-name` | `object` | - | -| `invalid-package-name.default` | `CallableMessage`<[`string`]\> | - | +| `invalid-package-name.default` | `CallableMessage`<[`"name"`]\> | - | | `model-not-in-package` | `object` | - | -| `model-not-in-package.default` | `CallableMessage`<[`string`]\> | - | +| `model-not-in-package.default` | `CallableMessage`<[`"name"`]\> | - | | `namespace-collision` | `object` | - | -| `namespace-collision.default` | `CallableMessage`<[`string`]\> | - | +| `namespace-collision.default` | `CallableMessage`<[`"name"`]\> | - | | `nested-array` | `object` | - | -| `nested-array.default` | `string` | "nested arrays are not supported by the Protobuf emitter" | +| `nested-array.default` | `"nested arrays are not supported by the Protobuf emitter"` | "nested arrays are not supported by the Protobuf emitter" | | `package` | `object` | - | -| `package.disallowed-option-type` | `CallableMessage`<[`string`, `string`]\> | - | +| `package.disallowed-option-type` | `CallableMessage`<[`"name"`, `"type"`]\> | - | | `root-operation` | `object` | - | -| `root-operation.default` | `string` | "operations in the root namespace are not supported (no associated Protobuf service)" | +| `root-operation.default` | `"operations in the root namespace are not supported (no associated Protobuf service)"` | "operations in the root namespace are not supported (no associated Protobuf service)" | | `unconvertible-enum` | `object` | - | -| `unconvertible-enum.default` | `string` | "enums must explicitly assign exactly one integer to each member to be used in a Protobuf message" | -| `unconvertible-enum.no-zero-first` | `string` | "the first variant of an enum must be set to zero to be used in a Protobuf message" | +| `unconvertible-enum.default` | `"enums must explicitly assign exactly one integer to each member to be used in a Protobuf message"` | "enums must explicitly assign exactly one integer to each member to be used in a Protobuf message" | +| `unconvertible-enum.no-zero-first` | `"the first variant of an enum must be set to zero to be used in a Protobuf message"` | "the first variant of an enum must be set to zero to be used in a Protobuf message" | | `unspeakable-template-argument` | `object` | - | -| `unspeakable-template-argument.default` | `CallableMessage`<[`string`]\> | - | +| `unspeakable-template-argument.default` | `CallableMessage`<[`"name"`]\> | - | | `unsupported-field-type` | `object` | - | -| `unsupported-field-type.recursive-map` | `string` | "a protobuf map's 'value' type may not refer to another map" | -| `unsupported-field-type.unconvertible` | `CallableMessage`<[`string`]\> | - | -| `unsupported-field-type.union` | `string` | "a message field's type may not be a union" | -| `unsupported-field-type.unknown-intrinsic` | `CallableMessage`<[`string`]\> | - | -| `unsupported-field-type.unknown-scalar` | `CallableMessage`<[`string`]\> | - | +| `unsupported-field-type.recursive-map` | `"a protobuf map's 'value' type may not refer to another map"` | "a protobuf map's 'value' type may not refer to another map" | +| `unsupported-field-type.unconvertible` | `CallableMessage`<[`"type"`]\> | - | +| `unsupported-field-type.union` | `"a message field's type may not be a union"` | "a message field's type may not be a union" | +| `unsupported-field-type.unknown-intrinsic` | `CallableMessage`<[`"name"`]\> | - | +| `unsupported-field-type.unknown-scalar` | `CallableMessage`<[`"name"`]\> | - | | `unsupported-input-type` | `object` | - | -| `unsupported-input-type.unconvertible` | `string` | "input parameters cannot be converted to a Protobuf message" | -| `unsupported-input-type.wrong-number` | `string` | "Protobuf methods must accept exactly one Model input (an empty model will do)" | -| `unsupported-input-type.wrong-type` | `string` | "Protobuf methods may only accept a named Model as an input" | +| `unsupported-input-type.unconvertible` | `"input parameters cannot be converted to a Protobuf message"` | "input parameters cannot be converted to a Protobuf message" | +| `unsupported-input-type.wrong-number` | `"Protobuf methods must accept exactly one Model input (an empty model will do)"` | "Protobuf methods must accept exactly one Model input (an empty model will do)" | +| `unsupported-input-type.wrong-type` | `"Protobuf methods may only accept a named Model as an input"` | "Protobuf methods may only accept a named Model as an input" | | `unsupported-intrinsic` | `object` | - | -| `unsupported-intrinsic.default` | `CallableMessage`<[`string`]\> | - | +| `unsupported-intrinsic.default` | `CallableMessage`<[`"name"`]\> | - | | `unsupported-return-type` | `object` | - | -| `unsupported-return-type.default` | `string` | "Protobuf methods must return a named Model" | +| `unsupported-return-type.default` | `"Protobuf methods must return a named Model"` | "Protobuf methods must return a named Model" | diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/00-index.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/00-index.md deleted file mode 100644 index 2680f3a0c5..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/00-index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Getting Started with TypeSpec For Http -pagination_next: getting-started/getting-started-http/setup # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183 ---- - -# Getting Started with TypeSpec for HTTP - -Let's create a REST API definition with TypeSpec. TypeSpec has an official HTTP API "binding" called `@typespec/http`. It's a set of TypeSpec declarations and decorators that describe HTTP APIs and can be used by code generators to generate OpenAPI descriptions, implementation code, and the like. Built on top of the HTTP library, there is the REST library `@typespec/rest` which provides some REST concepts like resources. - -TypeSpec also has an official OpenAPI emitter called `@typespec/openapi3` that consumes the HTTP API bindings and emits standard [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) descriptions. This can then be fed into any OpenAPI code generation pipeline. - -Additionally, TypeSpec includes the `@typespec/versioning` library for handling service versioning. - -References: - -- [HTTP library](../../libraries/http/reference) -- [REST library](../../libraries/rest/reference) -- [OpenAPI 3 emitter](../../emitters/openapi3/reference) -- [Versioning library](../../libraries/versioning/reference) diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/01-setup.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/01-setup.md deleted file mode 100644 index 8f6c0c8d64..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/01-setup.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Setup ---- - -# Setup - -:::note -Make sure to have installed the [editor extension](../../introduction/installation.md#install-the-vs-and-vscode-extensions) to get syntax highlighting and IntelliSense. -::: - -1. Make a new folder somewhere. -2. Run `tsp init` and select the `Generic REST API` template. -3. Run `tsp install` to install dependencies. -4. Run `tsp compile .` to compile the initial file. You can either run `tsp compile . --watch` to automatically compile changes on save or keep running the command manually after that. - -Resulting file structure: - -``` -main.tsp -tspconfig.yaml -package.json -node_modules/ -tsp-output/ - @typespec/ - openapi3/ - openapi.yaml -``` diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/02-service-definition.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/02-service-definition.md deleted file mode 100644 index a29cafc36d..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/02-service-definition.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Service Definition and Metadata ---- - -# Service Definition and Metadata - -A service definition in TypeSpec is a namespace that contains all the operations for the service. This namespace can carry top-level metadata such as the service name and version. TypeSpec provides several decorators to specify this metadata. While these decorators are optional, they add valuable information that can be used by tools and code generators to produce more informative and accurate outputs: - -- **`@service`**: Marks a namespace as a service namespace. It accepts the following options: - - `title`: The name of the service. -- **`@server`**: (From `TypeSpec.Http`) Specifies the host of the service. It can also accept parameters to define dynamic parts of the URL. - -Here's an example that uses these to define a Pet Store service: - -```typespec -import "@typespec/http"; -import "@typespec/rest"; -import "@typespec/versioning"; - -using TypeSpec.Http; -using TypeSpec.Rest; -using TypeSpec.Versioning; - -/** - * This is a sample Pet Store server. - */ -@service({ - title: "Pet Store Service", -}) -@server("https://example.com", "Single server endpoint") -namespace PetStore; -``` - -The `@server` decorator can take a third parameter with additional parameters as necessary: - -```typespec -@server("https://{region}.foo.com", "Regional endpoint", { - /** Region name */ - region?: string = "westus", -}) -``` diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/03-versioning.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/03-versioning.md deleted file mode 100644 index 2b27d29b25..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/03-versioning.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Versioning ---- - -# Versioning - -TypeSpec includes the `@typespec/versioning` library for handling service versioning. This library allows you to define different versions of your API and manage changes over time. - -Versioning is important for maintaining backward compatibility and ensuring that clients can continue to use your API as it evolves. - -It may seem premature to introduce versioning before we even have a spec, but it's worthwhile to consider versioning from the beginning of your API design process to avoid breaking changes later on. - -## Using the `@versioned` decorator - -The `@versioned` decorator is used to mark a namespace as versioned by a provided enum. This enum describes the supported versions of the service. - -Here's an example that extends our Pet Store service to include versioning: - -```typespec -import "@typespec/http"; -import "@typespec/rest"; -import "@typespec/versioning"; - -using TypeSpec.Http; -using TypeSpec.Rest; -using TypeSpec.Versioning; - -/** - * This is a sample Pet Store server. - */ -@service({ - title: "Pet Store Service", -}) -@server("https://example.com", "Single server endpoint") -@versioned(Versions) -namespace PetStore; -enum Versions { - v1: "1.0.0", - v2: "2.0.0", -} -``` - -We'll make use of the versioning introduced here in an upcoming section of this guide. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/04-resources-routes-status.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/04-resources-routes-status.md deleted file mode 100644 index cdd3451a73..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/04-resources-routes-status.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Resources, Routes, and Status Codes ---- - -# Resources, Routes, and Status Codes - -## Resources and Routes - -A resource is a general term for anything that can be identified by a URI and manipulated by HTTP methods. In TypeSpec, the operations for a resource are typically grouped in a route namespace. You declare a route namespace by adding the `@route` decorator to provide the path to that resource: - -```typespec -@route("/pets") -namespace Pets { - -} -``` - -Namespaces can be nested to encapsulate different levels of information. For example, you can have a `Pets` namespace that contains operations for managing pets, and a `Toys` namespace that contains operations for managing pet toys, all within the `PetStore` namespace. - -Let's add a `Pets` namespace within the `Petstore` namespace, and a `Pet` model to represent unique pets. `Toys` will be added in a later section to demonstrate versioning. - -```typespec -namespace PetStore { - enum Versions { - v1: "1.0.0", - v2: "2.0.0", - } - - @route("/pets") - namespace Pets { - @added(Versions.v1) - model Pet { - @minLength(1) - name: string; - - @minValue(0) - @maxValue(100) - age: int32; - - kind: "dog" | "cat" | "fish" | "bird" | "reptile"; - } - } -} -``` - -To define operations on this resource, you need to provide the HTTP verbs for the route using `operation` decorators. If an HTTP method decorator is not specified, then the default is `@post` if there is a body and `@get` otherwise. - -## Status Codes - -HTTP status codes are used to indicate the result of an HTTP request. They provide information about whether the request was successful, if there was an error, or if additional action is needed. In TypeSpec, you can use the `@statusCode` decorator to specify the status codes for your API responses. - -### Common HTTP Status Codes - -Here are some common HTTP status codes and their meanings: - -- **200 OK**: The request was successful, and the server returned the requested resource. -- **201 Created**: The request was successful, and a new resource was created. -- **204 No Content**: The request was successful, but there is no content to return. -- **400 Bad Request**: The server could not understand the request due to invalid syntax. -- **401 Unauthorized**: The client must authenticate itself to get the requested response. -- **403 Forbidden**: The client does not have access rights to the content. -- **404 Not Found**: The server cannot find the requested resource. -- **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. - -### Using the `@statusCode` Decorator - -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. - -```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; - } | { - @statusCode statusCode: 400; - @body error: Error; - }; -} -``` - -**Note**: The `@body` decorator and error handling are introduced here but will be covered in detail in later sections. - -### Handling Multiple Status Codes - -By using discriminated unions, you can handle multiple status codes in a single operation. This allows you to provide detailed responses based on different conditions. - -For example, let's add error handling to the `create` operation: - -```typespec -@route("/pets") -namespace Pets { - @post - op create(@body pet: Pet): { - @statusCode statusCode: 201; - } | { - @statusCode statusCode: 400; - @body error: Error; - }; -} -``` - -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. -- If there is a validation error, the operation returns a `400 Bad Request` status code with an error message. - -By defining status codes for your API responses, you can provide clear and consistent feedback to clients, making it easier for them to understand and handle different scenarios. This helps improve the overall user experience and ensures that your API is robust and reliable. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/05-error-handling.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/05-error-handling.md deleted file mode 100644 index 3525054c26..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/05-error-handling.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Error Handling ---- - -# Error Handling - -Error handling is a crucial aspect of API design. It ensures that clients receive meaningful feedback when something goes wrong, allowing them to handle errors gracefully. - -Common error scenarios include validation errors, authorization errors, resource not found errors, and server errors. - -## Defining Error Models - -In TypeSpec, you can define custom error models to represent different types of errors. These models can include properties such as error codes, messages, and additional details. - -```typespec -@error -model ValidationError { - code: "VALIDATION_ERROR"; - message: string; - details: string[]; -} - -@error -model NotFoundError { - code: "NOT_FOUND"; - message: string; -} - -@error -model InternalServerError { - code: "INTERNAL_SERVER_ERROR"; - message: string; -} -``` - -## Handling Different Types of Errors - -You can handle different types of errors by defining operations that return multiple possible responses using discriminated unions. - -```typespec -@route("/pets") -namespace Pets { - @post - op create(@body pet: Pet): { - @statusCode statusCode: 201; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; -} -``` - -## Best Practices - -- **Consistent Error Response Format**: Use a consistent format for all error responses to make it easier for clients to handle errors. -- **Meaningful Error Messages**: Provide clear and actionable error messages to help clients understand what went wrong and how to fix it. -- **Standard HTTP Status Codes**: Use standard HTTP status codes to indicate the type of error (e.g., 400 for validation errors, 404 for not found errors, 500 for server errors). diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/06-path-query-parameters.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/06-path-query-parameters.md deleted file mode 100644 index dfeccfa389..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/06-path-query-parameters.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Path and Query Parameters ---- - -# Path and Query Parameters - -In TypeSpec, you can specify parameters that should be passed in the URL path or as query parameters. This is done using the `@path` and `@query` decorators, respectively. - -## Path Parameters - -Path parameters are parts of the URL that are variable and are used to identify specific resources. They are marked with the `@path` decorator. These parameters are appended to the URL unless a substitution with that parameter name exists in the resource path. - -For example, let's define a `read` operation that retrieves a specific pet by its ID: - -```typespec -@route("/pets") -namespace Pets { - op read(@path petId: int32): { - @statusCode statusCode: 200; - @body pet: Pet; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - }; -} -``` - -In this example, `petId` is a path parameter. The resulting URL for this operation might look like `/pets/123`, where `123` is the value of `petId`. - -## Query Parameters - -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: - -```typespec -@route("/pets") -namespace Pets { - op list(@query skip?: int32, @query top?: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; -} -``` - -In this example, `skip` and `top` are query parameters. The resulting URL for this operation might look like `/pets?skip=10&top=20`, where `skip` and `top` are used to control pagination. - -## Combining Path and Query Parameters - -You can combine path and query parameters in a single operation. For example, let's define a `search` operation that retrieves pets by their type and supports pagination: - -```typespec -@route("/pets/{type}") -namespace Pets { - model Pet { - @minLength(1) - name: string; - - @minValue(0) - @maxValue(100) - age: int32; - - kind: "dog" | "cat" | "fish" | "bird" | "reptile"; - } - - op search(@path type: string, @query skip?: int32, @query top?: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; -} -``` - -In this example, `type` is a path parameter, and `skip` and `top` are query parameters. The resulting URL for this operation might look like `/pets/dog?skip=10&top=20`, where `dog` is the value of `type`, and `skip` and `top` are used for pagination. - -By using the `@path` and `@query` decorators, you can clearly define how parameters should be passed in the URL, making your API more intuitive and easier to use. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/07-headers.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/07-headers.md deleted file mode 100644 index 75a8ee76e6..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/07-headers.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Headers ---- - -# Headers - -Headers are used to pass additional information with the request or response. Model properties and parameters that should be passed in a header use the `@header` decorator. The decorator takes the header name as a parameter. If a header name is not provided, it is inferred from the property or parameter name. - -## Using the `@header` Decorator - -The `@header` decorator can be used to specify headers in both requests and responses. Here are some common use cases: - -- **Authorization**: Passing authentication tokens. -- **Content-Type**: Specifying the media type of the resource. -- **Custom Headers**: Any application-specific headers. - -### Example: Authorization Header - -Let's add an `Authorization` header to a request: - -```typespec -@route("/pets") -namespace Pets { - op list(@header Authorization: string): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; -} -``` - -### Example: Content-Type Header - -Let's specify the `Content-Type` header in a response: - -```typespec -@route("/pets") -namespace Pets { - op create(@header Authorization: string, @body pet: Pet): { - @statusCode statusCode: 201; - @header Content-Type: "application/json"; - }; -} -``` - -In this example, the `Content-Type` header is used to specify that the response body is in JSON format. - -## Example: `etag` Header - -`etag` stands for "entity tag" and is a part of HTTP headers used for web cache validation and conditional requests from browsers for resources. It is a unique identifier assigned by a web server to a specific version of a resource found at a URL. If the resource content changes, a new and different `etag` is assigned. - -Let's update our pet store operations to include new operations and update existing operations with relevant headers: - -```typespec -@route("/pets") -namespace Pets { - op list(@header Authorization: string, @query skip: int32, @query top: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; - - op read(@header Authorization: string, @path petId: int32, @header ifMatch?: string): { - @statusCode statusCode: 200; - @header eTag: string; - @body pet: Pet; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - }; - - @post - op create(@header Authorization: string, @body pet: Pet): { - @statusCode statusCode: 201; - @header Content-Type: "application/json"; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; - - @put - op update(@header Authorization: string, @path petId: int32, @body pet: Pet): { - @statusCode statusCode: 200; - @header Content-Type: "application/json"; - @body updatedPet: Pet; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; - - @delete - op delete(@header Authorization: string, @path petId: int32): { - @statusCode statusCode: 204; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; -} -``` - -In this example: - -- The `Authorization` header is used in all operations to pass an authentication token. -- The `ifMatch` header is used in the `read` operation to specify the `etag` value that the client has. The server can then compare this value with the current `etag` of the resource. -- The `eTag` header is included in the `read` response to provide the current `etag` value of the resource. -- The `Content-Type` header is used in the `create` and `update` operations to specify that the response body is in JSON format. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/08-request-response-bodies.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/08-request-response-bodies.md deleted file mode 100644 index bad19793f3..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/08-request-response-bodies.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Request and Response Bodies ---- - -# Request and Response Bodies - -Request and response bodies can be declared explicitly using the `@body` decorator. This decorator helps to clearly indicate which part of the model is the body of the request or response. While it may not change the API's functionality, it provides several benefits: - -1. **Clarity and readability**: Using the `@body` decorator makes it explicit which part of the model is intended to be the body. This can improve the readability of the code, making it easier for developers to understand the structure of the API. -2. **Consistency**: Applying the `@body` decorator consistently across your API definitions can help maintain a uniform style. This can be particularly useful in larger projects with multiple contributors. -3. **Tooling and documentation**: Some tools and documentation generators may rely on the `@body` decorator to produce more accurate and detailed outputs. By explicitly marking the body, you ensure that these tools can correctly interpret and document your API. - -Let's revisit some of or pet store operations that use the `@body` decorator: - -```typespec -@route("/pets") -namespace Pets { - model Pet { - @minLength(1) - name: string; - - @minValue(0) - @maxValue(100) - age: int32; - - kind: "dog" | "cat" | "fish" | "bird" | "reptile"; - } - - op list(@header Authorization: string, @query skip?: int32, @query top?: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; - - op read(@header Authorization: string, @path petId: int32): { - @statusCode statusCode: 200; - @body pet: Pet; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - }; - - @post - op create(@header Authorization: string, @body pet: Pet): { - @statusCode statusCode: 201; - @header contentType: "application/json"; - @body message: string; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; -} -``` - -### Explanation - -- **Pet Model**: The `Pet` model defines the structure of a pet with fields for `name`, `age`, and `kind`. - - - `name`: A string field with a minimum length of 1. - - `age`: An integer field with a minimum value of 0 and a maximum value of 100. - - `kind`: A string field that can be one of "dog", "cat", "fish", "bird", or "reptile". - -- **list Operation**: The `list` operation returns a list of pets. The response body is explicitly marked with the `@body` decorator to indicate that it contains an array of `Pet` objects. - -- **read Operation**: The `read` operation retrieves a specific pet by its ID. The response body is explicitly marked with the `@body` decorator to indicate that it contains a `Pet` object. - -- **create Operation**: The `create` operation creates a new pet. The request body is explicitly marked with the `@body` decorator to indicate that it contains a `Pet` object. This means that when a client sends a request to create a new pet, the request body must include the `name`, `age`, and `kind` fields as defined in the `Pet` model. - -### Example Request for Create Operation - -Here is an example of what the request body might look like when creating a new pet: - -```json -{ - "name": "Buddy", - "age": 5, - "kind": "dog" -} -``` - -This JSON object matches the structure of the `Pet` model, with fields for `name`, `age`, and `kind`. - -### Implicit vs. Explicit `@body` - -Note that in the absence of an explicit `@body`: - -1. **Request Body**: The set of parameters that are not marked with `@header`, `@query`, or `@path` will automatically form the request body. - -2. **Response Body**: The set of properties of the return model that are not marked with `@header`, `@query`, or `@path` will automatically form the response body. - -3. **Non-Model Return Types**: If the return type of an operation is not a model (e.g., a primitive type like `string` or `int32`), then that return type itself defines the response body. For example, if an operation returns a `string` without using the `@body` decorator, the `string` will be the response body. - -Here's an example to illustrate these points: - -```typespec -@route("/example") -namespace Example { - op implicitBody(param1: string, param2: int32): string { - // param1 and param2 form the request body - // The return type (string) forms the response body - } -} -``` - -In this example: - -- `param1` and `param2` are not marked with `@header`, `@query`, or `@path`, so they automatically form the request body. -- The return type is `string`, so the response body is the `string` itself. - -### `@bodyRoot` Decorator - -The `@bodyRoot` decorator is used when you want to specify that the entire body of the request or response should be a single value, rather than an object with multiple properties. This is useful when the body is a primitive type or a single model instance. - -#### Example - -Let's revisit some of our pet store operations that can benefit from using the `@bodyRoot` decorator: - -```typespec -@route("/pets") -namespace Pets { - @post - op create(@header Authorization: string, @bodyRoot pet: Pet): { - @statusCode statusCode: 201; - @header contentType: "application/json"; - @bodyRoot message: string; - } | { - @statusCode statusCode: 400; - @bodyRoot error: ValidationError; - } | { - @statusCode statusCode: 500; - @bodyRoot error: InternalServerError; - }; - - op read(@header Authorization: string, @path petId: int32): { - @statusCode statusCode: 200; - @header eTag: string; - @bodyRoot pet: Pet; - } | { - @statusCode statusCode: 404; - @bodyRoot error: NotFoundError; - }; -} -``` - -In this example: - -- The `@bodyRoot` decorator is used to indicate that the entire request body for the `create` operation is the `pet` parameter. -- The `@bodyRoot` decorator is also used to indicate that the entire response body for the `create` and `read` operations is either the `message`, `pet`, or `error` value. - -### Recommendation - -While TypeSpec can infer the request and response bodies in the absence of an explicit `@body` decorator, this can sometimes be confusing for developers. Therefore, it is recommended to use the `@body` decorator explicitly to clearly indicate which part of the model is intended to be the body. This improves the readability and maintainability of your API definitions. - -Similarly, use the `@bodyRoot` decorator when the entire body should be a single value. This makes it clear that the body is not an object with multiple properties, but a single entity, improving clarity and consistency in your API definitions. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/09-interfaces.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/09-interfaces.md deleted file mode 100644 index 1932d70704..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/09-interfaces.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Interfaces ---- - -# Interfaces - -In TypeSpec, an interface is a way to define a set of operations that can be grouped together. Interfaces are particularly useful when you want to apply the same set of operations to different resources or when you want to use automatic route generation, covered in the next section. - -## Defining an Interface - -Let's define an interface for managing pet toys. Since we've decided to extend our pet store service to support toys, we'll need to version the service. We'll add support for toys in version 2 of our pet store service: - -```typespec -@added(Versions.v2) -interface ToyOperations { - @get - getToy(@path petId: int32, @path toyId: int32): Toy | NotFoundError; - - @put - updateToy(@path petId: int32, @path toyId: int32, @body toy: Toy): Toy | NotFoundError; -} -``` - -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. - -## Using Interfaces - -Interfaces can be used to group operations that apply to different resources. This helps in maintaining a consistent structure and reusing common operations. - -We'll use the `ToyOperations` interface to automatically generate routs and operations for managing pet toys in the next section. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/10-automatic-route-generation.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/10-automatic-route-generation.md deleted file mode 100644 index 455823344c..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/10-automatic-route-generation.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Resources and Routes ---- - -# Automatic Route Generation - -Automatic route generation in TypeSpec allows you to generate URL paths for your API operations automatically, reducing the need to manually specify routes. This is achieved using the `@autoRoute` decorator. - -### Key Concepts - -- **@autoRoute**: Automatically generates routes for operations in an interface. -- **@path**: Marks a parameter as part of the URL path. -- **@segment**: Defines the specific part of the URL path that the parameter belongs to. - -### Example: Managing Pet Toys - -Let's extend our Pet Store example to include operations for managing pet toys. We'll define a `Toy` model and use the `ToyOperations` interface we previously defined to generate operations for getting and updating toy information. We'll define a `CommonParameters` model to define common path parameters for both pet and toy operations. - -Additionally, we'll use the `@added` decorator to indicate that these operations are part of version 2 of the service. - -#### Step 1: Define Common Parameters - -```typespec -model CommonParameters { - @path - @segment("pets") - petId: int32; - - @added(Versions.v2) - @path - @segment("toys") - toyId: int32; -} -``` - -- **CommonParameters**: This model defines common path parameters for pets and toys. - - `petId`: Part of the URL segment `/pets/{petId}`. - - `toyId`: Part of the URL segment `/toys/{toyId}`. - -#### Step 2: Define the Toy Model - -```typespec -@added(Versions.v2) -model Toy { - name: string; -} -``` - -- **Toy**: This model defines the structure of a toy, with a `name` property. - -#### Step 3: Extend the ToyOperations Interface to use Common Parameters - -```typespec -@autoRoute -interface ToyOperations { - @added(Versions.v2) - @get - getToy(...CommonParameters): Toy | NotFoundError; - - @added(Versions.v2) - @put - updateToy(...CommonParameters, toy: Toy): Toy | NotFoundError; -} -``` - -#### Resulting Routes - -The `@autoRoute` decorator and the `CommonParameters` model will generate the following routes for the operations: - -```text -/pets/{petId}/toys/{toyId} -``` - -By using the @autoRoute decorator in TypeSpec, you can significantly simplify the process of defining routes for your API operations. This approach not only reduces the need for manual route specification but also ensures consistency and reduces the likelihood of errors. - -Automatic route generation is particularly useful when dealing with complex APIs that have multiple nested resources, as it allows you to maintain a clear and organized structure. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/11-summary.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/11-summary.md deleted file mode 100644 index 8acc9041c1..0000000000 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started-http/11-summary.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Summary ---- - -# Summary - -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"]}" -import "@typespec/http"; -import "@typespec/rest"; -import "@typespec/versioning"; - -using TypeSpec.Http; -using TypeSpec.Rest; -using TypeSpec.Versioning; - -/** - * This is a sample Pet Store server. - */ -@service({ - title: "Pet Store Service", -}) -@server("https://example.com", "Single server endpoint") -@versioned(Versions) -namespace PetStore; -enum Versions { - v1: "1.0.0", - v2: "2.0.0", -} - -@route("/pets") -namespace Pets { - @added(Versions.v1) - model Pet { - @minLength(1) - name: string; - - @minValue(0) - @maxValue(100) - age: int32; - - kind: "dog" | "cat" | "fish" | "bird" | "reptile"; - } - - op list(@header Authorization: string, @query skip?: int32, @query top?: int32): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; - - op read(@header Authorization: string, @path petId: int32, @header ifMatch?: string): { - @statusCode statusCode: 200; - @header eTag: string; - @body pet: Pet; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - }; - - @post - op create(@header Authorization: string, @body pet: Pet): { - @statusCode statusCode: 201; - @header contentType: "application/json"; - @body message: string; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; - - @put - op update(@header Authorization: string, @path petId: int32, @body pet: Pet): - | { - @statusCode statusCode: 200; - @header contentType: "application/json"; - @body updatedPet: Pet; - } - | { - @statusCode statusCode: 404; - @body error: NotFoundError; - } - | { - @statusCode statusCode: 400; - @body error: ValidationError; - } - | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; - - @delete - op delete(@header Authorization: string, @path petId: int32): { - @statusCode statusCode: 204; - } | { - @statusCode statusCode: 404; - @body error: NotFoundError; - } | { - @statusCode statusCode: 500; - @body error: InternalServerError; - }; - - // Search operation combining path and query parameters - op search( - @header Authorization: string, - @path type: string, - @query skip?: int32, - @query top?: int32, - ): { - @statusCode statusCode: 200; - @body pets: Pet[]; - }; -} - -model CommonParameters { - @path - @segment("pets") - petId: int32; - - @added(Versions.v2) - @path - @segment("toys") - toyId: int32; -} - -@added(Versions.v2) -model Toy { - name: string; -} - -@error -model ValidationError { - code: "VALIDATION_ERROR"; - message: string; - details: string[]; -} - -@error -model NotFoundError { - code: "NOT_FOUND"; - message: string; -} - -@error -model InternalServerError { - code: "INTERNAL_SERVER_ERROR"; - message: string; -} - -@autoRoute -interface ToyOperations { - @added(Versions.v2) - @get - getToy(...CommonParameters): Toy | NotFoundError; - - @added(Versions.v2) - @put - updateToy(...CommonParameters, toy: Toy): Toy | NotFoundError; -} -``` - -Running `tsp compile .` will generate two versions of the OpenAPI description for this service in your `tsp-output` folder, one for each version defined in the `Versions` enum. - -``` -tsp-output/ -┗ @typespec/ - ┗ openapi3/ -┃ ┣ openapi.1.0.0.yaml -┃ ┗ openapi.2.0.0.yaml -``` diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/01-setup-basic-syntax.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/01-setup-basic-syntax.md new file mode 100644 index 0000000000..e08e16f64f --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/01-setup-basic-syntax.md @@ -0,0 +1,336 @@ +--- +id: 01-setup-basic-syntax +title: Getting Started with TypeSpec For REST APIs +pagination_next: getting-started/getting-started-rest/02-operations-responses # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183 +--- + +# Getting Started with TypeSpec for REST APIs + +## Introduction + +Welcome to the first part of our tutorial on using TypeSpec to define REST APIs with HTTP. In this section, we'll introduce you to TypeSpec, help you set up your environment, and cover the basic syntax and structure of TypeSpec. By the end of this section, you'll have a solid foundation to build upon in the subsequent sections. + +Before we start writing TypeSpec code, we need to set up our development environment. For detailed instructions on setting up your environment, please refer to the [Installation Guide](../../introduction/installation.md). + +### Summary of Setup and Installation + +1. **Install Node.js**: Download and install Node.js from [nodejs.org](https://nodejs.org/). +2. **Install TypeSpec CLI**: Run `npm install -g @typespec/compiler` to install the TypeSpec CLI. +3. **Verify Installation**: Run `tsp --version` to verify that the TypeSpec CLI is installed correctly. +4. **Create a New Project**: + - Run `tsp init` and select the `Generic REST API` template. + - Run `tsp install` to install dependencies. + - Run `tsp compile .` to compile the initial file. You can also run `tsp compile . --watch` to automatically compile changes on save. + +## Basic Syntax and Structure + +Now that we have our environment set up, let's dive into the basic syntax and structure of TypeSpec. We'll start with a simple example to illustrate the key concepts. + +### Import and Using Statements + +Before defining models and services, we need to import the necessary TypeSpec libraries and make them available in our namespace. + +As we progress through the tutorial, you can follow along by updating the `main.tsp` file in your project and compiling the changes to see the results reflected in the generated `openapi.yaml` specification. + +In most cases throughout this tutorial, you can alternatively use the `Try it` feature with the code samples to view the generated OpenAPI spec in your browser via the TypeSpec Playground. + +Let's begin by adding the following import and using statements to the `main.tsp` file: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; +``` + +In this example: + +- `import` statement brings in the [TypeSpec HTTP library](../../libraries/http/reference/), which provides the decorators and models we'll be using to define our REST API. +- `using` statement makes the imported library available in the current namespace, allowing us to use its features and decorators. + +### Understanding Models + +In TypeSpec, a [model](../../language-basics/models.md) is a fundamental building block used to define the structure of data. Models are used to represent entities, such as a `Pet`, with various properties that describe the entity's attributes. + +### Example: Defining a Simple Model + +Let's define a simple model for a `Pet`: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +model Pet { + id: int32; + name: string; + age: int32; + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} +``` + +In this example: + +- The `model` keyword is used to define a new model named `Pet`. +- The `Pet` model has four properties: `id`, `name`, `age`, and `kind`. +- The `petType` [`enum`](../../language-basics/enums.md) defines possible values for the `kind` property. + +### Example: Adding Validation Annotations + +We can add [validation](../../language-basics/values#validation) annotations to our model properties to enforce certain constraints: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} +``` + +In this example: + +- `@minLength(1)` ensures that the `name` property has at least one character. +- `@minValue(0)` and `@maxValue(100)` ensure that the `age` property is between 0 and 100. + +## Defining a REST Service + +A REST service in TypeSpec is defined using the [`@service`](../../standard-library/built-in-decorators#@service) decorator. This decorator allows you to specify metadata about your service, such as its title. Additionally, you can use the [`@server`](../../libraries/http/reference/decorators#@TypeSpec.Http.server) decorator to define the server endpoint where your service will be hosted. + +### Example: Defining a Service with a Title and Server Endpoint + +Let's start by defining a simple REST service for a Pet Store: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; +``` + +In this example: + +- The `@service` decorator is used to define a service with the title "Pet Store". +- The `@server` decorator specifies the server endpoint for the service, which is "https://example.com". + +## Organizing with Namespaces + +[Namespaces](../../language-basics/namespaces.md) in TypeSpec help you organize your models and operations logically. They act as containers for related definitions, making your API easier to manage and understand. + +### Example: Creating a Namespace + +Let's create a namespace for our Pet Store service: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; +``` + +In this example: + +- The `namespace` keyword is used to define a namespace named `PetStore`. +- All models and operations related to the Pet Store service will be defined within this namespace. + +## Adding Models to the Namespace + +Next, we'll add the `Pet` model we defined earlier to our `PetStore` namespace. + +### Example: Adding the Pet Model + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} +``` + +In this example: + +- The `Pet` model is defined within the `PetStore` namespace. +- The model includes validation annotations to enforce constraints on the properties. +- The `petType` enum is also defined within the `PetStore` namespace. + +## Defining HTTP Operations + +Now that we have our service, namespace, and model defined, let's add some HTTP [operations](../../language-basics/operations.md) to interact with our `Pet` model. We'll start with a simple `GET` operation to list all pets. + +### Example: Defining a GET Operation + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; +} +``` + +In this example: + +- The `@route` decorator is used to define the base path for the `Pets` namespace. +- The `@get` decorator defines a `GET` operation named `listPets`. +- The `listPets` operation returns a list of `Pet` objects in the response body. + +### Example: Defining a GET Operation with Path Parameter + +Let's add another `GET` operation to retrieve a specific pet by its `petId`. + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} +``` + +In this example: + +- The `getPet` operation retrieves a specific pet by its `petId` and returns it in the response body. +- If the pet is not found, it returns a `NotFoundError`, a custom error we've defined within the PetStore namespace. We'll cover error handling in more detail in a later section. + +## Conclusion + +In this section, we introduced you to TypeSpec, set up the development environment, and covered the basic syntax and structure of TypeSpec. We defined a simple model with validation annotations, created a REST service with a title and server endpoint, organized our API using namespaces, and added a model and HTTP operations. + +In the next section, we'll dive deeper into defining more HTTP operations and handling different types of responses. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/02-operations-responses.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/02-operations-responses.md new file mode 100644 index 0000000000..4ad41541de --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/02-operations-responses.md @@ -0,0 +1,345 @@ +--- +id: 02-operations-responses +title: Operations and Responses +--- + +# Operations and Responses + +## Introduction + +In this section, we'll build upon the basics we covered in the previous section and guide you through expanding your REST API using TypeSpec. We'll define more HTTP operations and handle different types of responses. + +## Defining More HTTP Operations + +Now that we have a basic `GET` operation to list all pets, let's add more operations to our API. We'll add operations for creating, updating, and deleting pets. + +### Example: Defining a POST Operation + +Let's define a `POST` operation to create a new pet: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} +``` + +In this example: + +- The `createPet` operation is defined using the `@post` decorator. +- It takes a `Pet` object in the request body and returns the created `Pet` object with a status code of 201. + +### Example: Defining a PUT Operation + +Let's define a `PUT` operation to update an existing pet: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): { + @body updatedPet: Pet; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} +``` + +In this example: + +- The `updatePet` operation is defined using the `@put` decorator. +- It takes a `petId` as a path parameter and a `Pet` object in the request body, returning the updated `Pet` object or a `NotFoundError`. + +### Example: Defining a DELETE Operation + +Let's define a `DELETE` operation to delete an existing pet: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): { + @body updatedPet: Pet; + } | { + @body error: NotFoundError; + }; + + @delete + op deletePet(@path petId: int32): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} +``` + +In this example: + +- The `deletePet` operation is defined using the `@delete` decorator. +- It takes a `petId` as a path parameter and returns a status code of 204 if the deletion is successful or a `NotFoundError` if the pet is not found. + +## Handling Different Types of Responses + +In a real-world API, different operations might return different types of responses. Let's see how we can handle various response scenarios in TypeSpec. + +### Example: Handling Validation Errors + +Let's define a `ValidationError` model and update our `createPet` operation to handle validation errors. + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): { + @body updatedPet: Pet; + } | { + @body error: NotFoundError; + }; + + @delete + op deletePet(@path petId: int32): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} +``` + +In this example: + +- The `ValidationError` model is defined to represent validation errors. +- The `createPet` operation is updated to handle validation errors by returning a status code of 400 and a `ValidationError` object. + +## Conclusion + +In this section, we expanded our REST API by defining more HTTP operations, including `POST`, `PUT`, and `DELETE` operations. We also demonstrated how to handle different types of responses, such as validation errors and not found errors. + +In the next section, we'll dive deeper into handling errors in your REST API, including defining custom response models for error handling. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/03-handling-errors.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/03-handling-errors.md new file mode 100644 index 0000000000..c5d4a4c798 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/03-handling-errors.md @@ -0,0 +1,338 @@ +--- +title: Handling Errors +--- + +# Handling Errors in Your REST API + +## Introduction + +In this section, we'll focus on handling errors in your REST API. We've already introduced defining error models in the previous sections, and now we'll expand on that topic. We'll define additional error models, create custom response models for error handling, and demonstrate how to use union types for different response scenarios. + +## Defining Error Models + +Error models can be used to represent different types of errors that your API might return. Let's start by defining some common error models. + +### Example: Defining Common Error Models + +We've already defined models to represent validation errors and not-found errors. We'll now add a model for internal server errors: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): { + @body updatedPet: Pet; + } | { + @body error: NotFoundError; + }; + + @delete + op deletePet(@path petId: int32): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} +``` + +In this example: + +- The `ValidationError`, `NotFoundError`, and `InternalServerError` models are defined to represent different types of errors. +- The `@error` decorator is used to indicate that these models represent error responses. + +## Custom Response Models for Error Handling + +Sometimes, you may need to create custom response models to handle specific error scenarios. Let's define a custom response model for the `InternalServerError` we just created. + +### Example: Defining a Custom Response Model + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): { + @body updatedPet: Pet; + } | { + @body error: NotFoundError; + } | InternalServerErrorResponse; + + @delete + op deletePet(@path petId: int32): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `InternalServerErrorResponse` model is defined to represent a custom response for a 500 Internal Server Error. +- The `updatePet` operation is updated to respond with with our custom `InternalServerErrorResponse` in case of an internal server error. + +## Union Expressions for Different Response Scenarios + +Union expressions are a type of [union](../../language-basics/unions.md) that allows you to define operations that can return different responses based on various scenarios. + +We've already seen some examples of this, let's expand on how we can use union types to handle different response scenarios in our operations. + +### Example: Using Union Expressions for Responses + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@route("/pets") +namespace Pets { + @get + op listPets(): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet): + | { + @body updatedPet: Pet; + } + | { + @body error: NotFoundError; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | InternalServerErrorResponse; + + @delete + op deletePet(@path petId: int32): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `updatePet` operation is updated to handle multiple response scenarios using union expressions. +- It can return an updated `Pet` object, a `NotFoundError`, a `ValidationError`, or an `InternalServerErrorResponse` custom response model. + +## Conclusion + +In this section, we focused on defining error handling in your REST API. We expanded on the topic of defining error models, created custom response models for error handling, and demonstrated how to use union expressions for different response scenarios. + +In the next section, we'll dive into reusing common parameters in your REST API. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/04-common-parameters.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/04-common-parameters.md new file mode 100644 index 0000000000..0ea3420282 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/04-common-parameters.md @@ -0,0 +1,195 @@ +--- +title: Common Parameters +--- + +# Reusing Common Parameters + +## Introduction + +In this section, we'll focus on reusing common parameters in your REST API. Common parameters are parameters that are used across multiple operations. By defining these parameters once and reusing them, we can make our API more consistent, easier to read, and easier to maintain. + +## Creating a Common Parameters Model + +Let's start by defining a model for common parameters. This model will include parameters that will be used across all pet store operations. + +### Example: Defining Common Parameters + +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`: + +```typespec +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +model CommonParameters { + @header + requestID: string; + + @query + locale?: string; + + @header + clientVersion?: string; +} +``` + +In this example: + +- The `@header` decorator is used to indicate that `requestID` and `clientVersion` are header parameters. +- The `@query` decorator is used to indicate that `locale` is a query parameter. + +## Reusing Common Parameters Across Multiple Operations + +Now that we have defined our common parameters model, let's reuse it across multiple operations in our API. + +### Example: Reusing Common Parameters in Operations + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +model CommonParameters { + @header + requestID: string; + + @query + locale?: string; + + @header + clientVersion?: string; +} + +@route("/pets") +namespace Pets { + @get + op listPets(...CommonParameters): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32, ...CommonParameters): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + op createPet(@body pet: Pet, ...CommonParameters): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): + | { + @body updatedPet: Pet; + } + | { + @body error: NotFoundError; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | InternalServerErrorResponse; + + @delete + op deletePet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `CommonParameters` model is reused across multiple operations using the [spread operator](../../language-basics/models#spread) `(...)`, which tells the TypeSpec compiler to expand the model definition inline. +- This approach ensures that the common parameters are consistently applied to all relevant operations, making the API more maintainable and reducing redundancy. + +## Conclusion + +In this section, we focused on reusing common parameters in your REST API using TypeSpec. By defining a common parameters model and reusing it across multiple operations, we can make our API more consistent, easier to read, and easier to maintain. + +In the next section, we'll dive into adding authentication to your REST API. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/05-authentication.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/05-authentication.md new file mode 100644 index 0000000000..b2f4ccb8cf --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/05-authentication.md @@ -0,0 +1,142 @@ +--- +title: Authentication +--- + +# Adding Authentication to Your REST API + +## Introduction + +In this section, we'll focus on adding authentication to your REST API. We'll introduce the `@useAuth` decorator, show how to enforce [authentication](../../libraries/http/authentication) on specific operations, and provide an example using Bearer authentication. + +## Introduction to the `@useAuth` Decorator + +The [@useAuth](../../libraries/http/reference/decorators#@TypeSpec.Http.useAuth) decorator is used to enforce authentication on specific operations in your REST API. This decorator allows you to specify the authentication mechanism that should be used for the operation. The TypeSpec HTTP library provides support for several authentication models, including `BearerAuth` for Bearer authentication. + +### Example: Enforcing Authentication on Specific Operations + +Let's update our existing operations to enforce authentication using the `@useAuth` decorator. We'll add authentication to the operations that modify pet data, such as creating, updating, and deleting pets. + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +model CommonParameters { + @header + requestID: string; + + @query + locale?: string; + + @header + clientVersion?: string; +} + +@route("/pets") +namespace Pets { + @get + op listPets(...CommonParameters): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32, ...CommonParameters): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + @useAuth(BearerAuth) + op createPet(@body pet: Pet, ...CommonParameters): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + @useAuth(BearerAuth) + op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): + | { + @body updatedPet: Pet; + } + | { + @body error: NotFoundError; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | InternalServerErrorResponse; + + @delete + @useAuth(BearerAuth) + op deletePet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `@useAuth(BearerAuth)` decorator is applied to the `createPet`, `updatePet`, and `deletePet` operations to enforce authentication using the Bearer authentication mechanism. +- Bearer authentication uses tokens for access control. The server generates a token upon login, and the client includes it in the Authorization header for protected resource requests. + +## Conclusion + +In this section, we focused on adding authentication to your REST API using TypeSpec. By using the `@useAuth` decorator, we can enforce authentication on specific operations, ensuring that only authorized clients can perform certain actions. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/06-versioning.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/06-versioning.md new file mode 100644 index 0000000000..4501523718 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/06-versioning.md @@ -0,0 +1,330 @@ +--- +title: Versioning +--- + +# Versioning + +## Introduction + +In this section, we'll focus on implementing versioning in your REST API. Versioning allows you to manage changes to your API over time without breaking existing clients. We'll introduce the `@versioned` decorator, show how to define versions with enums, and demonstrate how to use the `@added` decorator to specify version-specific models and operations. + +## Adding the Versioning Library + +Before we can use the versioning decorators, we need to add the `@typespec/versioning` library to our project. This involves updating the `package.json` file and installing the necessary dependencies. + +### Step 1: Update `package.json` + +Add the `@typespec/versioning` library to your `package.json` file: + +```json +{ + "name": "tsp_pet_store", + "version": "0.1.0", + "type": "module", + "dependencies": { + "@typespec/compiler": "latest", + "@typespec/http": "latest", + "@typespec/openapi3": "latest", + "@typespec/versioning": "latest" + }, + "private": true +} +``` + +### Step 2: Install Dependencies + +Run the following command to install the new dependencies: + +```sh +tsp install +``` + +## Introduction to the `@versioned` Decorator + +The [`@versioned`](../../libraries/versioning/reference/decorators#@TypeSpec.Versioning.versioned) decorator is used to define different versions of your API. This decorator allows you to specify the versions that your API supports and manage changes across these versions. + +### Example: Defining API Versions + +Let's define two versions of our API, `v1` and `v2`: + +```typespec +import "@typespec/http"; +import "@typespec/versioning"; + +using TypeSpec.Http; +using TypeSpec.Versioning; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +@versioned(Versions) +namespace PetStore; + +enum Versions { + v1: "1.0", + v2: "2.0", +} +``` + +In this example: + +- We're importing and using a new module, `@typespec/versioning`, which provides versioning support. +- The `@versioned` decorator is used to define the versions supported by the API, defined in the `Versions` enum. +- The `Versions` enum specifies two versions: `v1` (1.0) and `v2` (2.0). + +## Using the `@added` Decorator + +The [`@added`](../../libraries/versioning/reference/decorators#@TypeSpec.Versioning.added) decorator is used to indicate that a model or operation was added in a specific version of the API. This allows you to manage changes and additions to your API over time. + +### Example: Adding a New Model in a Specific Version + +Let's add a `Toy` model that is only available in version 2 of the API: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; +import "@typespec/versioning"; + +using TypeSpec.Http; +using TypeSpec.Versioning; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +@versioned(Versions) +namespace PetStore; + +enum Versions { + v1: "1.0", + v2: "2.0", +} + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@added(Versions.v2) +model Toy { + id: int32; + name: string; +} +``` + +In this example: + +- The `Toy` model is defined with the `@added(Versions.v2)` decorator to indicate that it was added in version 2 of the API. + +## Version-Specific Operations + +Let's define version-specific operations to manage toys for pets. These operations will only be available in version 2 of the API. + +### Example: Adding Version-Specific Operations + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; +import "@typespec/versioning"; + +using TypeSpec.Http; +using TypeSpec.Versioning; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +@versioned(Versions) +namespace PetStore; + +enum Versions { + v1: "1.0", + v2: "2.0", +} + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@added(Versions.v2) +model Toy { + id: int32; + name: string; +} + +model CommonParameters { + @header + requestID: string; + + @query + locale?: string; + + @header + clientVersion?: string; +} + +@route("/pets") +namespace Pets { + @get + op listPets(...CommonParameters): { + @body pets: Pet[]; + }; + + @get + op getPet(@path petId: int32, ...CommonParameters): { + @body pet: Pet; + } | { + @body error: NotFoundError; + }; + + @post + @useAuth(BearerAuth) + op createPet(@body pet: Pet, ...CommonParameters): { + @statusCode statusCode: 201; + @body newPet: Pet; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + }; + + @put + @useAuth(BearerAuth) + op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): + | { + @body updatedPet: Pet; + } + | { + @body error: NotFoundError; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | InternalServerErrorResponse; + + @delete + @useAuth(BearerAuth) + op deletePet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 204; + } | { + @body error: NotFoundError; + }; + + @route("{petId}/toys") + namespace Toys { + @added(Versions.v2) + @get + op listToys(@path petId: int32, ...CommonParameters): { + @body toys: Toy[]; + }; + + @added(Versions.v2) + @post + @useAuth(BearerAuth) + op createToy(@path petId: int32, @body toy: Toy, ...CommonParameters): { + @statusCode statusCode: 201; + @body newToy: Toy; + }; + + @added(Versions.v2) + @put + @useAuth(BearerAuth) + op updateToy(@path petId: int32, @path toyId: int32, @body toy: Toy, ...CommonParameters): { + @body updatedToy: Toy; + }; + + @added(Versions.v2) + @delete + @useAuth(BearerAuth) + op deleteToy(@path petId: int32, @path toyId: int32, ...CommonParameters): { + @statusCode statusCode: 204; + }; + } +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `Toys` namespace is defined under the `Pets` namespace. +- The `@added(Versions.v2)` decorator is applied to the operations within the `Toys` namespace to indicate that they were added in version 2 of the API. +- The `Toys` namespace includes operations to list, create, update, and delete toys for a specific pet. These operations are only available in version 2 of the API. + +### Generating OpenAPI Specifications for Different Versions + +Once we start adding versions, the TypeSpec compiler will generate individual OpenAPI specifications for each version. In our case, it will generate two OpenAPI specs, one for each version of our pet store service API. Our file structure will now look like this: + +``` +main.tsp +tspconfig.yaml +package.json +node_modules/ +tsp-output/ +┗ @typespec/ + ┗ openapi3/ +┃ ┣ openapi.1.0.yaml +┃ ┗ openapi.2.0.yaml +``` + +The 2.0 version of the OpenAPI spec will include the Toy model and any other additions specified for version 2 of our service, while the 1.0 version will not include these additions. + +Generating separate specs for each version ensures backward compatibility, provides clear documentation for developers to understand differences between versions, and simplifies maintenance by allowing independent updates to each version's specifications. + +## Conclusion + +In this section, we focused on implementing versioning in your REST API. By using the `@versioned` and `@added` decorators, we can manage changes to our API over time without breaking existing clients. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/07-custom-response-models.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/07-custom-response-models.md new file mode 100644 index 0000000000..2fddaa65eb --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/07-custom-response-models.md @@ -0,0 +1,287 @@ +--- +title: Custom Response Models +--- + +# Custom Response Models + +## Introduction + +In this section, we'll focus on creating custom response models. We'll define custom response models, extend base response models, and demonstrate how to use them in your API operations. We'll also incorporate existing response models from the TypeSpec HTTP library. + +## Introduction to Custom Response Models + +Custom response models allow you to define structured responses for your API operations. They help ensure consistency and clarity in your API responses. TypeSpec defines response models for common HTTP responses in the [HTTP library](https://typespec.io/docs/libraries/http/reference), which we can incorporate into our custom response models. + +### Benefits of Using Custom Response Models + +- **Reducing Duplication**: By defining common response structures once, you can reuse them across multiple operations. +- **Improving Readability**: Custom response models make your API definitions clearer and easier to understand. +- **Minimizing Errors**: Consistent response models help reduce the likelihood of errors in your API responses. + +## Defining Custom Response Models + +Let's start by defining some basic custom response models. We'll incorporate existing response models from the TypeSpec HTTP library. + +### Example: Defining Basic Custom Response Models + +```typespec +import "@typespec/http"; +import "@typespec/versioning"; + +using TypeSpec.Http; +using TypeSpec.Versioning; + +model PetListResponse { + ...OkResponse; + ...Body; +} + +model PetResponse { + ...OkResponse; + ...Body; +} + +model PetCreatedResponse { + ...CreatedResponse; + ...Body; +} + +model PetErrorResponse { + ...BadRequestResponse; + ...Body; +} +``` + +In this example: + +- `PetListResponse` extends `OkResponse` and includes a body with an array of `Pet` objects. +- `PetResponse` extends `OkResponse` and includes a body with a single `Pet` object. +- `PetCreatedResponse` extends `CreatedResponse` and includes a body with a newly created `Pet` object. +- `PetErrorResponse` extends `BadRequestResponse` and includes a body with a `ValidationError` object. + +## Extending Base Response Models + +We can extend base response models to create more specific responses for different scenarios. + +### Example: Extending Base Response Models + +```typespec +model PetNotFoundResponse { + ...NotFoundResponse; + ...Body; +} + +model PetUnauthorizedResponse { + ...UnauthorizedResponse; + ...Body; +} + +model PetSuccessResponse { + ...OkResponse; + ...Body; +} +``` + +In this example: + +- `PetNotFoundResponse` extends `NotFoundResponse` and includes a body with a `NotFoundError` object. +- `PetUnauthorizedResponse` extends `UnauthorizedResponse` and includes a body with an `APIError` object. +- `PetSuccessResponse` extends `OkResponse` and includes a body with a success message. + +## Using Custom Response Models in Operations + +Now that we have defined our custom response models, let's use them in our API operations. + +### Example: Applying Custom Response Models to Operations + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; +import "@typespec/versioning"; + +using TypeSpec.Http; +using TypeSpec.Versioning; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +@versioned(Versions) +namespace PetStore; + +enum Versions { + v1: "1.0", + v2: "2.0", +} + +model Pet { + id: int32; + + @minLength(1) + name: string; + + @minValue(0) + @maxValue(100) + age: int32; + + kind: petType; +} + +enum petType { + dog: "dog", + cat: "cat", + fish: "fish", + bird: "bird", + reptile: "reptile", +} + +@added(Versions.v2) +model Toy { + id: int32; + name: string; +} + +model CommonParameters { + @header + requestID: string; + + @query + locale?: string; + + @header + clientVersion?: string; +} + +model PetListResponse { + ...OkResponse; + ...Body; +} + +model PetResponse { + ...OkResponse; + ...Body; +} + +model PetCreatedResponse { + ...CreatedResponse; + ...Body; +} + +model PetErrorResponse { + ...BadRequestResponse; + ...Body; +} + +model PetNotFoundResponse { + ...NotFoundResponse; + ...Body; +} + +model PetUnauthorizedResponse { + ...UnauthorizedResponse; + ...Body; +} + +model PetSuccessResponse { + ...OkResponse; + ...Body; +} + +@route("/pets") +namespace Pets { + @get + op listPets(...CommonParameters): PetListResponse | BadRequestResponse; + + @get + op getPet( + @path petId: int32, + @header ifMatch?: string, + ): PetResponse | PetNotFoundResponse | BadRequestResponse; + + @useAuth(BearerAuth) + @post + op createPet(@body pet: Pet): PetCreatedResponse | PetErrorResponse; + + @useAuth(BearerAuth) + @put + op updatePet(@path petId: int32, @body pet: Pet): + | PetResponse + | PetNotFoundResponse + | PetUnauthorizedResponse + | InternalServerErrorResponse; + + @useAuth(BearerAuth) + @delete + op deletePet( + @path petId: int32, + ): PetNotFoundResponse | PetSuccessResponse | PetUnauthorizedResponse; + + @route("{petId}/toys") + namespace Toys { + @added(Versions.v2) + @get + op listToys(@path petId: int32, ...CommonParameters): { + @body toys: Toy[]; + }; + + @added(Versions.v2) + @post + @useAuth(BearerAuth) + op createToy(@path petId: int32, @body toy: Toy, ...CommonParameters): { + @statusCode statusCode: 201; + @body newToy: Toy; + }; + + @added(Versions.v2) + @put + @useAuth(BearerAuth) + op updateToy(@path petId: int32, @path toyId: int32, @body toy: Toy, ...CommonParameters): { + @body updatedToy: Toy; + }; + + @added(Versions.v2) + @delete + @useAuth(BearerAuth) + op deleteToy(@path petId: int32, @path toyId: int32, ...CommonParameters): { + @statusCode statusCode: 204; + }; + } +} + +@error +model NotFoundError { + code: "NOT_FOUND"; + message: string; +} + +@error +model ValidationError { + code: "VALIDATION_ERROR"; + message: string; + details: string[]; +} + +@error +model InternalServerError { + code: "INTERNAL_SERVER_ERROR"; + message: string; +} + +model InternalServerErrorResponse { + @statusCode statusCode: 500; + @body error: InternalServerError; +} +``` + +In this example: + +- The `listPets` operation uses the `PetListResponse` custom response model. +- The `getPet` operation uses the `PetResponse`, `PetNotFoundResponse`, and `BadRequestResponse` custom response models. +- The `createPet` operation uses the `PetCreatedResponse` and `PetErrorResponse` custom response models. +- The `updatePet` operation uses the `PetResponse`, `PetNotFoundResponse`, `PetUnauthorizedResponse`, and `InternalServerErrorResponse` custom response models. +- The `deletePet` operation uses the `PetNotFoundResponse`, `PetSuccessResponse`, and `PetUnauthorizedResponse` custom response models. + +Note that we could also define custom response models for the `Toys` operations, similar to the `Pets` operations. But for brevity, we're omitting them in this example. + +## Conclusion + +In this section, we focused on creating custom response models in your REST API. By defining and using custom response models, we can reduce duplication, improve readability, and minimize errors in our API responses. We also incorporated existing response models from the TypeSpec HTTP library to ensure consistency and clarity. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/08-conclusion.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/08-conclusion.md new file mode 100644 index 0000000000..163081d73e --- /dev/null +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started-rest/08-conclusion.md @@ -0,0 +1,33 @@ +--- +title: Conclusion +--- + +# Conclusion + +## Recap of Key Concepts + +Throughout this tutorial, we've covered a wide range of topics to help you build a comprehensive REST API using TypeSpec. Here's a brief recap of the main concepts we explored: + +- **Setting Up the Environment**: We started by setting up the development environment and installing the necessary tools. +- **Defining Models and Services**: We learned how to define models and services using TypeSpec. +- **Creating and Organizing Namespaces**: We organized our API using namespaces to group related models and operations. +- **Defining HTTP Operations**: We defined various HTTP operations, including GET, POST, PUT, and DELETE. +- **Handling Errors**: We created error models and custom response models to handle different types of errors. +- **Reusing Common Parameters**: We defined common parameters and reused them across multiple operations. +- **Adding Authentication**: We enforced authentication on specific operations using the `@useAuth` decorator. +- **Implementing Versioning**: We implemented versioning in our API using the `@versioned` and `@added` decorators. +- **Creating Custom Response Models**: We created custom response models to reduce duplication and improve readability. + +## Further Resources + +To continue learning and exploring TypeSpec, here are some additional resources: + +- [TypeSpec Documentation](https://typespec.io/docs): The official documentation provides detailed information on TypeSpec features and usage. +- [TypeSpec GitHub Repository](https://github.com/microsoft/typespec): The GitHub repository contains the source code and examples. +- [TypeSpec Discord Server](https://aka.ms/typespec/discord): Join the TypeSpec Discord server to participate in discussions, ask questions, and connect with the community. + +## Feedback and Community Engagement + +We value your feedback and would love to hear about your experiences with this tutorial. Please feel free to share your thoughts and suggestions. + +Join the TypeSpec community on Discord to engage with other developers, ask questions, and contribute to discussions. Your participation helps us improve and grow the TypeSpec ecosystem. diff --git a/packages/website/versioned_docs/version-latest/getting-started/getting-started.md b/packages/website/versioned_docs/version-latest/getting-started/getting-started.md index e047f4e543..46f112b1e5 100644 --- a/packages/website/versioned_docs/version-latest/getting-started/getting-started.md +++ b/packages/website/versioned_docs/version-latest/getting-started/getting-started.md @@ -5,5 +5,4 @@ title: Getting Started # Getting started with TypeSpec -- [Get started with TypeSpec for HTTP](./getting-started-http/getting-started-http-00 - .md) +- [Get started with TypeSpec for REST](./getting-started-rest/01-setup-basic-syntax.md) diff --git a/packages/website/versioned_docs/version-latest/introduction/installation.md b/packages/website/versioned_docs/version-latest/introduction/installation.md index f58bf57551..af6653557f 100644 --- a/packages/website/versioned_docs/version-latest/introduction/installation.md +++ b/packages/website/versioned_docs/version-latest/introduction/installation.md @@ -26,7 +26,7 @@ npm install -g @typespec/compiler ## Install the VS and VSCode extensions -TypeSpec provides extension for the following editors: +TypeSpec provides extensions for the following editors: - [Visual Studio Code](./editor/vscode.md) - [Visual Studio](./editor/vs.md) @@ -50,13 +50,27 @@ tsp install You should now have a basic TypeSpec project setup with a structure looking like this: ```bash -package.json # Package manifest defining your TypeSpec project as a Node package. -tspconfig.yaml # TypeSpec project configuration letting you configure emitters, emitter options, compiler options, etc. -main.tsp # TypeSpec entrypoint +main.tsp +tspconfig.yaml +package.json +node_modules/ +tsp-output/ + @typespec/ + openapi3/ + openapi.yaml ``` +- **main.tsp**: The entry point for your TypeSpec build. This file typically contains the main definitions for your models, services, and operations. +- **tspconfig.yaml**: Configuration file for the TypeSpec compiler, specifying options and settings for the build process. +- **package.json**: Contains metadata about the project, including dependencies, scripts, and other project-related information. +- **node_modules/**: Directory where npm installs the project's dependencies. +- **tsp-output/**: Directory where the TypeSpec compiler outputs generated files. +- **openapi.yaml**: The generated OpenAPI specification file for your API, detailing the API's endpoints, models, and operations. The output can vary based on the target format specified in the `tspconfig.yaml` file. + ## Compile project ```bash tsp compile . ``` + +You can also run `tsp compile . --watch` to automatically compile changes on save. diff --git a/packages/website/versioned_docs/version-latest/libraries/http/encoding.md b/packages/website/versioned_docs/version-latest/libraries/http/encoding.md index e680334c62..7f665c4fe9 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/encoding.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/encoding.md @@ -134,3 +134,41 @@ model User { + +## Numeric types ( `int64`, `decimal128`, `float64`, etc.) + +By default numeric types are serialized as a JSON number. However for large types like `int64` or `decimal128` that cannot be represented in certain languages like JavaScript it is recommended to serialize them as string over the wire. + + + + + + + +
TypeSpecExample payload
+ +```tsp +model User { + id: int64; // JSON number + + @encode(string) + idAsString: int64; // JSON string + + viaSalar: decimalString; +} + +@encode(string) +scalar decimalString extends decimal128; +``` + + + +```json +{ + "id": 1234567890123456789012345678901234567890, + "idAsString": "1234567890123456789012345678901234567890", + "viaSalar": "1.3" +} +``` + +
diff --git a/packages/website/versioned_docs/version-latest/libraries/http/examples.md b/packages/website/versioned_docs/version-latest/libraries/http/examples.md new file mode 100644 index 0000000000..f6b0700c9d --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/examples.md @@ -0,0 +1,30 @@ +--- +title: Examples +--- + +# Http Examples + +See [examples docs](../../standard-library/examples.md) for general information about examples. + +## Multiple responses + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using Http; + +@opExample(#{ returnType: #{ statusCode: 200, name: "Max", age: 3 } }) +@opExample(#{ returnType: #{ statusCode: 404, error: "Not found" } }) +@opExample(#{ returnType: #{ statusCode: 422, error: "Invalid payload" } }) +op read(): { + @statusCode statusCode: 200; + name: string; + age: int32; +} | { + @statusCode statusCode: 404; + error: string; +} | { + @statusCode statusCode: 422; + error: string; +}; +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/http/operations.md b/packages/website/versioned_docs/version-latest/libraries/http/operations.md index 382a274374..9071328c5d 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/operations.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/operations.md @@ -133,7 +133,7 @@ namespace Pets { **Configure:** -Use the `@header` decorator on a property named `statusCode` to declare a status code for a response. Generally, setting this to just `int32` isn't particularly useful. Instead, use number literal types to create a discriminated union of response types. Let's add status codes to our responses, and add a 404 response to our read endpoint. +Use the `@statusCode` decorator on a property to declare a status code for a response. Generally, setting this to just `int32` isn't particularly useful. Instead, use number literal types to create a discriminated union of response types. Let's add status codes to our responses, and add a 404 response to our read endpoint. ```typespec @route("/pets") diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/data-types.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/data-types.md index dc8106701e..549e8fc88d 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/data-types.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/data-types.md @@ -466,6 +466,21 @@ model TypeSpec.Http.PasswordFlow | refreshUrl? | `string` | the refresh URL | | scopes? | `string[]` | list of scopes for the credential | +### `PathOptions` {#TypeSpec.Http.PathOptions} + +```typespec +model TypeSpec.Http.PathOptions +``` + +#### Properties + +| Name | Type | Description | +| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name? | `string` | Name of the parameter in the uri template. | +| explode? | `boolean` | When interpolating this parameter in the case of array or object expand each value using the given style.
Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | +| style? | `"simple" \| "label" \| "matrix" \| "fragment" \| "path"` | Different interpolating styles for the path parameter.
- `simple`: No special encoding.
- `label`: Using `.` separator.
- `matrix`: `;` as separator.
- `fragment`: `#` as separator.
- `path`: `/` as separator. | +| allowReserved? | `boolean` | When interpolating this parameter do not encode reserved characters.
Equivalent of adding `+` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | + ### `PlainData` {#TypeSpec.Http.PlainData} Produces a new model with the same properties as T, but with `@query`, @@ -495,10 +510,11 @@ model TypeSpec.Http.QueryOptions #### Properties -| Name | Type | Description | -| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- | -| name? | `string` | Name of the query when included in the url. | -| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. | +| Name | Type | Description | +| -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| name? | `string` | Name of the query when included in the url. | +| explode? | `boolean` | If true send each value in the array/object as a separate query parameter.
Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)

\| Style \| Explode \| Uri Template \| Primitive value id = 5 \| Array id = [3, 4, 5] \| Object id = {"role": "admin", "firstName": "Alex"} \|
\| ------ \| ------- \| -------------- \| ---------------------- \| ----------------------- \| -------------------------------------------------- \|
\| simple \| false \| `/users{?id}` \| `/users?id=5` \| `/users?id=3,4,5` \| `/users?id=role,admin,firstName,Alex` \|
\| simple \| true \| `/users{?id*}` \| `/users?id=5` \| `/users?id=3&id=4&id=5` \| `/users?role=admin&firstName=Alex` \| | +| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used.
**DEPRECATED**: use explode: true instead of `multi` or `@encode` | ### `Response` {#TypeSpec.Http.Response} @@ -542,6 +558,12 @@ Describes the location of the API key enum TypeSpec.Http.ApiKeyLocation ``` +| Name | Value | Description | +| ------ | ----- | ---------------------------- | +| header | | API key is a header value | +| query | | API key is a query parameter | +| cookie | | API key is found in a cookie | + ### `AuthType` {#TypeSpec.Http.AuthType} Authentication type @@ -550,6 +572,14 @@ Authentication type enum TypeSpec.Http.AuthType ``` +| Name | Value | Description | +| ------------- | ----- | -------------- | +| http | | HTTP | +| apiKey | | API key | +| oauth2 | | OAuth2 | +| openIdConnect | | OpenID connect | +| noAuth | | Empty auth | + ### `OAuth2FlowType` {#TypeSpec.Http.OAuth2FlowType} Describes the OAuth2 flow type @@ -557,3 +587,10 @@ Describes the OAuth2 flow type ```typespec enum TypeSpec.Http.OAuth2FlowType ``` + +| Name | Value | Description | +| ----------------- | ----- | ----------------------- | +| authorizationCode | | authorization code flow | +| implicit | | implicit flow | +| password | | password flow | +| clientCredentials | | client credential flow | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/decorators.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/decorators.md index 26c688c55b..a55f429071 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/decorators.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/decorators.md @@ -278,7 +278,7 @@ None Explicitly specify that this property is to be interpolated as a path parameter. ```typespec -@TypeSpec.Http.path(paramName?: valueof string) +@TypeSpec.Http.path(paramNameOrOptions?: valueof string | TypeSpec.Http.PathOptions) ``` #### Target @@ -287,9 +287,9 @@ Explicitly specify that this property is to be interpolated as a path parameter. #### Parameters -| Name | Type | Description | -| --------- | ---------------- | --------------------------------------------------- | -| paramName | `valueof string` | Optional name of the parameter in the url template. | +| Name | Type | Description | +| ------------------ | --------------------------------------------- | -------------------------------------------------------------- | +| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. | #### Examples @@ -347,7 +347,7 @@ None Specify this property is to be sent as a query parameter. ```typespec -@TypeSpec.Http.query(queryNameOrOptions?: string | TypeSpec.Http.QueryOptions) +@TypeSpec.Http.query(queryNameOrOptions?: valueof string | TypeSpec.Http.QueryOptions) ``` #### Target @@ -356,30 +356,20 @@ Specify this property is to be sent as a query parameter. #### Parameters -| Name | Type | Description | -| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | -| queryNameOrOptions | `string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | +| Name | Type | Description | +| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------- | +| queryNameOrOptions | `valueof string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | #### Examples ```typespec op read(@query select: string, @query("order-by") orderBy: string): void; -op list( - @query({ - name: "id", - format: "multi", - }) - ids: string[], -): void; +op list(@query(#{ name: "id", explode: true }) ids: string[]): void; ``` ### `@route` {#@TypeSpec.Http.route} -Defines the relative route URI for the target operation - -The first argument should be a URI fragment that may contain one or more path parameter fields. -If the namespace or interface that contains the operation is also marked with a `@route` decorator, -it will be used as a prefix to the route URI of the operation. +Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) `@route` can only be applied to operations, namespaces, and interfaces. @@ -393,21 +383,35 @@ it will be used as a prefix to the route URI of the operation. #### Parameters -| Name | Type | Description | -| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof string` | Relative route path. Cannot include query parameters. | -| options | `{...}` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | | +| options | `{...}` | _DEPRECATED_ Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples +##### Simple path parameter + ```typespec -@route("/widgets") -op getWidget(@path id: string): Widget; +@route("/widgets/{id}") op getWidget(@path id: string): Widget; +``` + +##### Reserved characters + +```typespec +@route("/files{+path}") op getFile(@path path: string): bytes; +``` + +##### Query parameter + +```typespec +@route("/files") op list(select?: string, filter?: string): Files[]; +@route("/files{?select,filter}") op listFullUriTemplate(select?: string, filter?: string): Files[]; ``` ### `@server` {#@TypeSpec.Http.server} -Specify the endpoint for this service. +Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints. ```typespec @TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record) @@ -433,7 +437,7 @@ Specify the endpoint for this service. namespace PetStore; ``` -##### parameterized +##### Parameterized ```typespec @server("https://{region}.foo.com", "Regional endpoint", { @@ -442,6 +446,21 @@ namespace PetStore; }) ``` +##### Multiple + +```typespec +@service +@server("https://example.com", "Standard endpoint") +@server( + "https://{project}.private.example.com", + "Private project endpoint", + { + project: string, + } +) +namespace PetStore; +``` + ### `@sharedRoute` {#@TypeSpec.Http.sharedRoute} `@sharedRoute` marks the operation as sharing a route path with other operations. diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/index.mdx b/packages/website/versioned_docs/version-latest/libraries/http/reference/index.mdx index d85da81df6..352ea8d952 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/index.mdx +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/index.mdx @@ -83,6 +83,7 @@ npm install --save-peer @typespec/http - [`OkResponse`](./data-types.md#TypeSpec.Http.OkResponse) - [`OpenIdConnectAuth`](./data-types.md#TypeSpec.Http.OpenIdConnectAuth) - [`PasswordFlow`](./data-types.md#TypeSpec.Http.PasswordFlow) +- [`PathOptions`](./data-types.md#TypeSpec.Http.PathOptions) - [`PlainData`](./data-types.md#TypeSpec.Http.PlainData) - [`QueryOptions`](./data-types.md#TypeSpec.Http.QueryOptions) - [`Response`](./data-types.md#TypeSpec.Http.Response) diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$path.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$path.md index 582811a325..24d9de6d05 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$path.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$path.md @@ -7,7 +7,7 @@ title: "[F] $path" function $path( context, target, - paramName?): void + paramNameOrOptions?): void ``` ## Parameters @@ -16,7 +16,7 @@ function $path( | ------ | ------ | | `context` | `DecoratorContext` | | `target` | `ModelProperty` | -| `paramName`? | `string` | +| `paramNameOrOptions`? | `string` \| `PathOptions` | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$query.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$query.md index 8e531d644e..d00b3e0b10 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$query.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$query.md @@ -16,7 +16,7 @@ function $query( | ------ | ------ | | `context` | `DecoratorContext` | | `target` | `ModelProperty` | -| `queryNameOrOptions`? | `Type` | +| `queryNameOrOptions`? | `string` \| `QueryOptions` | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getOperationParameters.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getOperationParameters.md index dc93c66c05..678b1dd90b 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getOperationParameters.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getOperationParameters.md @@ -7,20 +7,20 @@ title: "[F] getOperationParameters" function getOperationParameters( program, operation, + partialUriTemplate, overloadBase?, - knownPathParamNames?, options?): [HttpOperationParameters, readonly Diagnostic[]] ``` ## Parameters -| Parameter | Type | Default value | -| ------ | ------ | ------ | -| `program` | `Program` | `undefined` | -| `operation` | `Operation` | `undefined` | -| `overloadBase`? | [`HttpOperation`](../interfaces/HttpOperation.md) | `undefined` | -| `knownPathParamNames`? | `string`[] | `[]` | -| `options`? | [`OperationParameterOptions`](../interfaces/OperationParameterOptions.md) | `{}` | +| Parameter | Type | +| ------ | ------ | +| `program` | `Program` | +| `operation` | `Operation` | +| `partialUriTemplate` | `string` | +| `overloadBase`? | [`HttpOperation`](../interfaces/HttpOperation.md) | +| `options`? | [`OperationParameterOptions`](../interfaces/OperationParameterOptions.md) | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/joinPathSegments.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/joinPathSegments.md new file mode 100644 index 0000000000..fdbcaeb93f --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/joinPathSegments.md @@ -0,0 +1,18 @@ +--- +jsApi: true +title: "[F] joinPathSegments" + +--- +```ts +function joinPathSegments(rest): string +``` + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `rest` | `string`[] | + +## Returns + +`string` diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/resolvePathAndParameters.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/resolvePathAndParameters.md index 7a6324b8fe..2b858a051a 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/resolvePathAndParameters.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/resolvePathAndParameters.md @@ -28,4 +28,4 @@ options): DiagnosticResult | ------ | ------ | | `parameters` | [`HttpOperationParameters`](../interfaces/HttpOperationParameters.md) | | `path` | `string` | -| `pathSegments` | `string`[] | +| `uriTemplate` | `string` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/index.md index bba96b2410..1b674a47e1 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/index.md @@ -58,9 +58,13 @@ title: "[P] JS API" - [HttpAuth](type-aliases/HttpAuth.md) - [HttpAuthRef](type-aliases/HttpAuthRef.md) +- [HttpOperationHeaderParameter](type-aliases/HttpOperationHeaderParameter.md) - [HttpOperationParameter](type-aliases/HttpOperationParameter.md) +- [HttpOperationPathParameter](type-aliases/HttpOperationPathParameter.md) +- [HttpOperationQueryParameter](type-aliases/HttpOperationQueryParameter.md) - [HttpOperationRequestBody](type-aliases/HttpOperationRequestBody.md) - [HttpOperationResponseBody](type-aliases/HttpOperationResponseBody.md) +- [HttpProperty](type-aliases/HttpProperty.md) - [HttpStatusCodes](type-aliases/HttpStatusCodes.md) - [HttpStatusCodesEntry](type-aliases/HttpStatusCodesEntry.md) - [HttpVerb](type-aliases/HttpVerb.md) @@ -149,6 +153,7 @@ title: "[P] JS API" - [isSharedRoute](functions/isSharedRoute.md) - [isStatusCode](functions/isStatusCode.md) - [isVisible](functions/isVisible.md) +- [joinPathSegments](functions/joinPathSegments.md) - [listHttpOperationsIn](functions/listHttpOperationsIn.md) - [reportIfNoRoutes](functions/reportIfNoRoutes.md) - [resolveAuthentication](functions/resolveAuthentication.md) diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HeaderFieldOptions.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HeaderFieldOptions.md index 771bc3677e..b55bd73360 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HeaderFieldOptions.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HeaderFieldOptions.md @@ -7,6 +7,6 @@ title: "[I] HeaderFieldOptions" | Property | Type | Description | | ------ | ------ | ------ | -| `format?` | \| `"form"` \| `"csv"` \| `"multi"` \| `"ssv"` \| `"tsv"` \| `"pipes"` \| `"simple"` | The string format of the array. "csv" and "simple" are used interchangeably, as are "multi" and "form". | +| `format?` | \| `"form"` \| `"multi"` \| `"csv"` \| `"ssv"` \| `"tsv"` \| `"simple"` \| `"pipes"` | The string format of the array. "csv" and "simple" are used interchangeably, as are "multi" and "form". | | `name` | `string` | - | | `type` | `"header"` | - | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperation.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperation.md index 3b8daa4636..8c2a0a314c 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperation.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperation.md @@ -5,15 +5,16 @@ title: "[I] HttpOperation" --- ## Properties -| Property | Type | Description | -| ------ | ------ | ------ | -| `authentication?` | [`Authentication`](Authentication.md) | Operation authentication. Overrides HttpService authentication | -| `container` | [`OperationContainer`](../type-aliases/OperationContainer.md) | Parent type being the interface, namespace or global namespace. | -| `operation` | `Operation` | Operation type reference. | -| `overloading?` | [`HttpOperation`](HttpOperation.md) | Overload this operation | -| `overloads?` | [`HttpOperation`](HttpOperation.md)[] | List of operations that overloads this one. | -| `parameters` | [`HttpOperationParameters`](HttpOperationParameters.md) | Parameters. | -| `path` | `string` | Route path | -| `pathSegments` | `string`[] | Path segments | -| `responses` | [`HttpOperationResponse`](HttpOperationResponse.md)[] | Responses. | -| `verb` | [`HttpVerb`](../type-aliases/HttpVerb.md) | Route verb. | +| Property | Modifier | Type | Description | +| ------ | ------ | ------ | ------ | +| `authentication?` | `public` | [`Authentication`](Authentication.md) | Operation authentication. Overrides HttpService authentication | +| `container` | `public` | [`OperationContainer`](../type-aliases/OperationContainer.md) | Parent type being the interface, namespace or global namespace. | +| `operation` | `public` | `Operation` | Operation type reference. | +| `overloading?` | `public` | [`HttpOperation`](HttpOperation.md) | Overload this operation | +| `overloads?` | `public` | [`HttpOperation`](HttpOperation.md)[] | List of operations that overloads this one. | +| `parameters` | `public` | [`HttpOperationParameters`](HttpOperationParameters.md) | Parameters. | +| `path` | `public` | `string` | Route path. Not recommended use [uriTemplate](HttpOperation.md) instead. This will not work for complex cases like not-escaping reserved chars. | +| ~~`pathSegments`~~ | `public` | `string`[] | Path segments **Deprecated** use [uriTemplate](HttpOperation.md) instead | +| `responses` | `public` | [`HttpOperationResponse`](HttpOperationResponse.md)[] | Responses. | +| `uriTemplate` | `readonly` | `string` | The fully resolved uri template as defined by http://tools.ietf.org/html/rfc6570. **Examples** `"/foo/{bar}/baz{?qux}"` `"/foo/{+path}"` | +| `verb` | `public` | [`HttpVerb`](../type-aliases/HttpVerb.md) | Route verb. | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationParameters.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationParameters.md index 9dc403173c..6654b39f27 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationParameters.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationParameters.md @@ -5,9 +5,10 @@ title: "[I] HttpOperationParameters" --- ## Properties -| Property | Type | Description | -| ------ | ------ | ------ | -| `body?` | [`HttpOperationBody`](HttpOperationBody.md) \| [`HttpOperationMultipartBody`](HttpOperationMultipartBody.md) | - | -| ~~`bodyParameter?`~~ | `ModelProperty` | **Deprecated** use body.parameter | -| ~~`bodyType?`~~ | `Type` | **Deprecated** use body.type | -| `parameters` | [`HttpOperationParameter`](../type-aliases/HttpOperationParameter.md)[] | - | +| Property | Modifier | Type | Description | +| ------ | ------ | ------ | ------ | +| `body?` | `public` | [`HttpOperationBody`](HttpOperationBody.md) \| [`HttpOperationMultipartBody`](HttpOperationMultipartBody.md) | - | +| ~~`bodyParameter?`~~ | `public` | `ModelProperty` | **Deprecated** use body.parameter | +| ~~`bodyType?`~~ | `public` | `Type` | **Deprecated** use body.type | +| `parameters` | `public` | [`HttpOperationParameter`](../type-aliases/HttpOperationParameter.md)[] | - | +| `properties` | `readonly` | [`HttpProperty`](../type-aliases/HttpProperty.md)[] | Http properties | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationResponseContent.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationResponseContent.md index 8eda6b012d..efb31abea0 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationResponseContent.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/HttpOperationResponseContent.md @@ -5,7 +5,8 @@ title: "[I] HttpOperationResponseContent" --- ## Properties -| Property | Type | -| ------ | ------ | -| `body?` | [`HttpOperationBody`](HttpOperationBody.md) \| [`HttpOperationMultipartBody`](HttpOperationMultipartBody.md) | -| `headers?` | `Record`<`string`, `ModelProperty`\> | +| Property | Modifier | Type | Description | +| ------ | ------ | ------ | ------ | +| `body?` | `public` | [`HttpOperationBody`](HttpOperationBody.md) \| [`HttpOperationMultipartBody`](HttpOperationMultipartBody.md) | - | +| `headers?` | `public` | `Record`<`string`, `ModelProperty`\> | - | +| `properties` | `readonly` | [`HttpProperty`](../type-aliases/HttpProperty.md)[] | Http properties for this response | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/PathParameterOptions.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/PathParameterOptions.md index cfc25786c6..9e89deb489 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/PathParameterOptions.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/PathParameterOptions.md @@ -3,9 +3,16 @@ jsApi: true title: "[I] PathParameterOptions" --- +## Extends + +- `Required`<`PathOptions`\> + ## Properties -| Property | Type | -| ------ | ------ | -| `name` | `string` | -| `type` | `"path"` | +| Property | Modifier | Type | Inherited from | +| ------ | ------ | ------ | ------ | +| `allowReserved` | `readonly` | `boolean` | `Required.allowReserved` | +| `explode` | `readonly` | `boolean` | `Required.explode` | +| `name` | `readonly` | `string` | `Required.name` | +| `style` | `readonly` | \| `"label"` \| `"path"` \| `"simple"` \| `"matrix"` \| `"fragment"` | `Required.style` | +| `type` | `public` | `"path"` | - | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/QueryParameterOptions.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/QueryParameterOptions.md index 8060b7cbf7..3e7f25ada3 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/QueryParameterOptions.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/QueryParameterOptions.md @@ -3,10 +3,15 @@ jsApi: true title: "[I] QueryParameterOptions" --- +## Extends + +- `Required`<`Omit`<`QueryOptions`, `"format"`\>\> + ## Properties -| Property | Type | Description | -| ------ | ------ | ------ | -| `format?` | \| `"form"` \| `"csv"` \| `"multi"` \| `"ssv"` \| `"tsv"` \| `"pipes"` \| `"simple"` | The string format of the array. "csv" and "simple" are used interchangeably, as are "multi" and "form". | -| `name` | `string` | - | -| `type` | `"query"` | - | +| Property | Modifier | Type | Description | Inherited from | +| ------ | ------ | ------ | ------ | ------ | +| `explode` | `readonly` | `boolean` | - | `Required.explode` | +| ~~`format?`~~ | `public` | \| `"form"` \| `"multi"` \| `"csv"` \| `"ssv"` \| `"tsv"` \| `"simple"` \| `"pipes"` | **Deprecated** use explode and `@encode` decorator instead. | - | +| `name` | `readonly` | `string` | - | `Required.name` | +| `type` | `public` | `"query"` | - | - | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/RouteProducerResult.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/RouteProducerResult.md index e4e75c82b8..fd0c3e2b19 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/RouteProducerResult.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/interfaces/RouteProducerResult.md @@ -8,4 +8,4 @@ title: "[I] RouteProducerResult" | Property | Type | | ------ | ------ | | `parameters` | [`HttpOperationParameters`](HttpOperationParameters.md) | -| `segments` | `string`[] | +| `uriTemplate` | `string` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationHeaderParameter.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationHeaderParameter.md new file mode 100644 index 0000000000..57dd1d59be --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationHeaderParameter.md @@ -0,0 +1,14 @@ +--- +jsApi: true +title: "[T] HttpOperationHeaderParameter" + +--- +```ts +type HttpOperationHeaderParameter: HeaderFieldOptions & object; +``` + +## Type declaration + +| Name | Type | +| ------ | ------ | +| `param` | `ModelProperty` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationParameter.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationParameter.md index d34ab4a82f..9d258e59e7 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationParameter.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationParameter.md @@ -4,11 +4,5 @@ title: "[T] HttpOperationParameter" --- ```ts -type HttpOperationParameter: HeaderFieldOptions | QueryParameterOptions | PathParameterOptions & object; +type HttpOperationParameter: HttpOperationHeaderParameter | HttpOperationQueryParameter | HttpOperationPathParameter; ``` - -## Type declaration - -| Name | Type | -| ------ | ------ | -| `param` | `ModelProperty` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationPathParameter.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationPathParameter.md new file mode 100644 index 0000000000..15cbfb7cf4 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationPathParameter.md @@ -0,0 +1,14 @@ +--- +jsApi: true +title: "[T] HttpOperationPathParameter" + +--- +```ts +type HttpOperationPathParameter: PathParameterOptions & object; +``` + +## Type declaration + +| Name | Type | +| ------ | ------ | +| `param` | `ModelProperty` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationQueryParameter.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationQueryParameter.md new file mode 100644 index 0000000000..9078e5e3d8 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpOperationQueryParameter.md @@ -0,0 +1,14 @@ +--- +jsApi: true +title: "[T] HttpOperationQueryParameter" + +--- +```ts +type HttpOperationQueryParameter: QueryParameterOptions & object; +``` + +## Type declaration + +| Name | Type | +| ------ | ------ | +| `param` | `ModelProperty` | diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpProperty.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpProperty.md new file mode 100644 index 0000000000..8e1901220a --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/type-aliases/HttpProperty.md @@ -0,0 +1,17 @@ +--- +jsApi: true +title: "[T] HttpProperty" + +--- +```ts +type HttpProperty: + | HeaderProperty + | ContentTypeProperty + | QueryProperty + | PathProperty + | StatusCodeProperty + | BodyProperty + | BodyRootProperty + | MultipartBodyProperty + | BodyPropertyProperty; +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/variables/$lib.md index d73165cfb8..a2f3ab23c0 100644 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/variables/$lib.md +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/variables/$lib.md @@ -39,7 +39,7 @@ const $lib: TypeSpecLibrary, | `duplicate-body.default` | `"Operation has multiple @body parameters declared"` | "Operation has multiple @body parameters declared" | | `duplicate-body.duplicateUnannotated` | `"Operation has multiple unannotated parameters. There can only be one representing the body"` | "Operation has multiple unannotated parameters. There can only be one representing the body" | | `duplicate-operation` | `object` | - | -| `duplicate-operation.default` | `CallableMessage`<[`string`, `string`, `string`]\> | - | +| `duplicate-operation.default` | `CallableMessage`<[`"operationName"`, `"verb"`, `"path"`]\> | - | | `duplicate-route-decorator` | `object` | - | | `duplicate-route-decorator.namespace` | `"@route was defined twice on this namespace and has different values."` | "@route was defined twice on this namespace and has different values." | | `formdata-no-part-name` | `object` | - | @@ -47,19 +47,21 @@ const $lib: TypeSpecLibrary, | `header-format-required` | `object` | - | | `header-format-required.default` | "A format must be specified for @header when type is an array. e.g. @header(\{format: \"csv\"\})" | - | | `http-file-extra-property` | `object` | - | -| `http-file-extra-property.default` | `CallableMessage`<[`string`]\> | - | +| `http-file-extra-property.default` | `CallableMessage`<[`"propName"`]\> | - | | `http-verb-duplicate` | `object` | - | -| `http-verb-duplicate.default` | `CallableMessage`<[`string`]\> | - | +| `http-verb-duplicate.default` | `CallableMessage`<[`"entityName"`]\> | - | +| `incompatible-uri-param` | `object` | - | +| `incompatible-uri-param.default` | `CallableMessage`<[`"param"`, `"uriKind"`, `"annotationKind"`]\> | - | | `invalid-type-for-auth` | `object` | - | -| `invalid-type-for-auth.default` | `CallableMessage`<[`string`]\> | - | +| `invalid-type-for-auth.default` | `CallableMessage`<[`"kind"`]\> | - | | `metadata-ignored` | `object` | - | -| `metadata-ignored.default` | `CallableMessage`<[`string`]\> | - | -| `missing-path-param` | `object` | - | -| `missing-path-param.default` | `CallableMessage`<[`string`]\> | - | +| `metadata-ignored.default` | `CallableMessage`<[`"kind"`]\> | - | | `missing-server-param` | `object` | - | -| `missing-server-param.default` | `CallableMessage`<[`string`]\> | - | +| `missing-server-param.default` | `CallableMessage`<[`"param"`]\> | - | +| `missing-uri-param` | `object` | - | +| `missing-uri-param.default` | `CallableMessage`<[`"param"`]\> | - | | `multipart-invalid-content-type` | `object` | - | -| `multipart-invalid-content-type.default` | `CallableMessage`<[`string`, `string`]\> | - | +| `multipart-invalid-content-type.default` | `CallableMessage`<[`"contentType"`, `"supportedContentTypes"`]\> | - | | `multipart-model` | `object` | - | | `multipart-model.default` | `"Multipart request body must be a model."` | "Multipart request body must be a model." | | `multipart-nested` | `object` | - | @@ -69,17 +71,17 @@ const $lib: TypeSpecLibrary, | `multiple-status-codes` | `object` | - | | `multiple-status-codes.default` | "Multiple \`@statusCode\` decorators defined for this operation response." | "Multiple \`@statusCode\` decorators defined for this operation response." | | `no-service-found` | `object` | - | -| `no-service-found.default` | `CallableMessage`<[`string`]\> | - | +| `no-service-found.default` | `CallableMessage`<[`"namespace"`]\> | - | | `operation-param-duplicate-type` | `object` | - | -| `operation-param-duplicate-type.default` | `CallableMessage`<[`string`, `string`]\> | - | +| `operation-param-duplicate-type.default` | `CallableMessage`<[`"paramName"`, `"types"`]\> | - | | `optional-path-param` | `object` | - | -| `optional-path-param.default` | `CallableMessage`<[`string`]\> | - | -| `query-format-required` | `object` | - | -| `query-format-required.default` | "A format must be specified for @query when type is an array. e.g. @query(\{format: \"multi\"\})" | - | +| `optional-path-param.default` | `CallableMessage`<[`"paramName"`]\> | - | | `shared-inconsistency` | `object` | - | -| `shared-inconsistency.default` | `CallableMessage`<[`string`, `string`]\> | - | +| `shared-inconsistency.default` | `CallableMessage`<[`"verb"`, `"path"`]\> | - | | `status-code-invalid` | `object` | - | | `status-code-invalid.default` | `"statusCode value must be a numeric or string literal or union of numeric or string literals"` | "statusCode value must be a numeric or string literal or union of numeric or string literals" | | `status-code-invalid.value` | `"statusCode value must be a three digit code between 100 and 599"` | "statusCode value must be a three digit code between 100 and 599" | +| `use-uri-template` | `object` | - | +| `use-uri-template.default` | `CallableMessage`<[`"param"`]\> | - | | `write-visibility-not-supported` | `object` | - | | `write-visibility-not-supported.default` | "@visibility(\"write\") is not supported. Use @visibility(\"update\"), @visibility(\"create\") or @visibility(\"create\", \"update\") as appropriate." | - | diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlEncodeData.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlEncodeData.md index b52c84826e..4f5b1e8700 100644 --- a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlEncodeData.md +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlEncodeData.md @@ -9,7 +9,7 @@ title: "[I] XmlEncodeData" ## Properties -| Property | Type | Overrides | -| ------ | ------ | ------ | -| `encoding` | `string` | `EncodeData.encoding` | -| `type` | `Scalar` | `EncodeData.type` | +| Property | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | +| `encoding?` | `string` | Known encoding key. Can be undefined when `@encode(string)` is used on a numeric type. In that case it just means using the base10 decimal representation of the number. | `EncodeData.encoding` | +| `type` | `Scalar` | - | `EncodeData.type` | diff --git a/packages/website/versioned_docs/version-latest/release-notes/release-2024-08-06.md b/packages/website/versioned_docs/version-latest/release-notes/release-2024-08-06.md new file mode 100644 index 0000000000..964373328c --- /dev/null +++ b/packages/website/versioned_docs/version-latest/release-notes/release-2024-08-06.md @@ -0,0 +1,164 @@ +--- +title: 0.59 - August 2024 +--- + +:::warning +This release contains deprecations breaking changes +::: + +## Breaking Changes + +### @typespec/compiler + +- [#4050](https://github.com/microsoft/typespec/pull/4050) Fix issue where naming a namespace with the same name as the blockless namespace would merge with it instead of creating a subnamespace like any other name would. + + ```tsp + namespace MyOrg.MyProject; + + namespace MyOrg.MyProject.MyArea { + model A {} + } + + namespace MyArea2 { + model B {} + } + ``` + + Previously model `A` would end-up in namespace `MyOrg.MyProject.MyArea` and model `B` in `MyOrg.MyProject.MyArea2`. With this change model `A` will now be in `MyOrg.MyProject.MyOrg.MyProject.MyArea`. To achieve the previous behavior the above code should be written as: + + ```tsp + namespace MyOrg.MyProject; + + namespace MyArea { + model A {} + } + + namespace MyArea2 { + model B {} + } + ``` + +### @typespec/json-schema + +- [#3558](https://github.com/microsoft/typespec/pull/3558) Updates `@extension` decorator to support TypeSpec values in addition to types. + +In previous versions of the json-schema emitter, the `@extension` decorator only accepted types as the value. These are emitted as JSON schemas. In order to add extensions as raw values, types had to be wrapped in the `Json<>` template when being passed to the `@extension` decorator. + +This change allows setting TypeSpec values (introduced in TypeSpec 0.57.0) directly instead. + +The following example demonstrates using values directly: + +```tsp +@extension("x-example", #{ foo: "bar" }) +model Foo {} +``` + +This change results in scalars being treated as values instead of types. This will result in the `@extension` decorator emitting raw values for scalar types instead of JSON schema. To preserve the previous behavior, use `typeof` when passing in a scalar value. + +The following example demonstrates how to pass a scalar value that emits a JSON schema: + +```tsp +@extension("x-example", "foo") +model Foo {} +``` + +To preserve this same behavior, the above example can be updated to the following: + +```tsp +@extension("x-example", typeof "foo") +model Foo {} +``` + +## Deprecations + +### @typespec/http + +- [#3932](https://github.com/microsoft/typespec/pull/3932) API deprecation: `HttpOperation#pathSegments` is deprecated. Use `HttpOperation#uriTemplate` instead. +- [#3932](https://github.com/microsoft/typespec/pull/3932) Deprecated `@query({format: })` option. Use `@query(#{explode: true})` instead of `form` or `multi` format. Previously `csv`/`simple` is the default now. + Decorator is also expecting an object value now instead of a model. A deprecation warning with a codefix will help migrating. + + ```diff + - @query({format: "form"}) select: string[]; + + @query(#{explode: true}) select: string[]; + ``` + +## Features + +### @typespec/compiler + +- [#3906](https://github.com/microsoft/typespec/pull/3906) Support completion for template parameter extending model or object value + + Example + + ```tsp + model User {} + alias user = User<{ + ┆: [age] | [name]; + }>; + ``` + +- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string +- [#4023](https://github.com/microsoft/typespec/pull/4023) Warn when using `\` in config file field that expect a path. +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add `ArrayEncoding` enum to define simple serialization of arrays + +### @typespec/http + +- [#4046](https://github.com/microsoft/typespec/pull/4046) API: Expose `properties: HttpProperty[]` on operation parameter and response which reference all the properties of interest(Body, statusCode, contentType, implicitBodyProperty, etc.) +- [#3932](https://github.com/microsoft/typespec/pull/3932) `@route` can now take a uri template as defined by [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) + + ```tsp + @route("files{+path}") download(path: string): void; + ``` + +### @typespec/rest + +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes + +### @typespec/openapi3 + +- [#3894](https://github.com/microsoft/typespec/pull/3894) Add support for `@useRef` on responses +- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string +- [#3890](https://github.com/microsoft/typespec/pull/3890) `@extension` used on the service namespace will set extension at the root of the document +- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes + +## Bug Fixes + +### @typespec/compiler + +- [#3881](https://github.com/microsoft/typespec/pull/3881) Fixes a bug where ending a non-terminal line in a multi-line comment with a backslash caused the next star to show up in the parsed doc string. +- [#4050](https://github.com/microsoft/typespec/pull/4050) Allow using compact namespace form `Foo.Bar` when inside another namespace + + ```tsp + namespace MyOrg.MyProject { + namespace MyModule.MySubmodule { // <-- this used to emit an error + // ... + + } + } + ``` + +- [#3898](https://github.com/microsoft/typespec/pull/3898) Fix decimal numeric with leading zeros +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix type comparison of literal and scalar when in projection context +- [#4022](https://github.com/microsoft/typespec/pull/4022) `tsp compile --watch` will not stop when a crash happens during compilation +- [#3933](https://github.com/microsoft/typespec/pull/3933) Add `const` template parameter to get the precise lib type + +### @typespec/http + +- [#3909](https://github.com/microsoft/typespec/pull/3909) Fix `HttpPart` not respecting explicit part name by always using the property name +- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message + +### @typespec/versioning + +- [#3911](https://github.com/microsoft/typespec/pull/3911) Allow spreading a model that has props added in previous version +- [#3951](https://github.com/microsoft/typespec/pull/3951) Fixes issue where spreading a versioned model as a parameter to an incompatible versioned operation would cause the compiler to crash. + +### @typespec/openapi3 + +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix issue where operation example would produce an empty object when `@body`/`@bodyRoot` was used +- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix operation response body examples showing up for each response. +- [#3912](https://github.com/microsoft/typespec/pull/3912) Fixes bug where union documentation was being applied to each union member in emitted output. +- [#3908](https://github.com/microsoft/typespec/pull/3908) Fixes bug where circular references in unions caused an empty object to be emitted instead of a ref. + +### @typespec/protobuf + +- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message diff --git a/packages/website/versioned_docs/version-latest/standard-library/built-in-data-types.md b/packages/website/versioned_docs/version-latest/standard-library/built-in-data-types.md index 66ad5be3c9..ae1639782f 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/built-in-data-types.md +++ b/packages/website/versioned_docs/version-latest/standard-library/built-in-data-types.md @@ -54,6 +54,9 @@ model ExampleOptions | description? | [`string`](#string) | Description of the example | ### `object` {#object} +:::warning +**Deprecated**: object is deprecated. Please use {} for an empty model, `Record` for a record with unknown property types, `unknown[]` for an array. +::: Represent a model ```typespec @@ -191,6 +194,19 @@ model UpdateableProperties #### Properties None +### `ArrayEncoding` {#ArrayEncoding} + +Encoding for serializing arrays +```typespec +enum ArrayEncoding +``` + +| Name | Value | Description | +|------|-------|-------------| +| pipeDelimited | | Each values of the array is separated by a \| | +| spaceDelimited | | Each values of the array is separated by a | + + ### `BytesKnownEncoding` {#BytesKnownEncoding} Known encoding to use on bytes @@ -198,6 +214,10 @@ Known encoding to use on bytes enum BytesKnownEncoding ``` +| Name | Value | Description | +|------|-------|-------------| +| base64 | `"base64"` | Encode to Base64 | +| base64url | `"base64url"` | Encode to Base64 Url | ### `DateTimeKnownEncoding` {#DateTimeKnownEncoding} @@ -207,6 +227,11 @@ Known encoding to use on utcDateTime or offsetDateTime enum DateTimeKnownEncoding ``` +| Name | Value | Description | +|------|-------|-------------| +| rfc3339 | `"rfc3339"` | RFC 3339 standard. https://www.ietf.org/rfc/rfc3339.txt
Encode to string. | +| rfc7231 | `"rfc7231"` | RFC 7231 standard. https://www.ietf.org/rfc/rfc7231.txt
Encode to string. | +| unixTimestamp | `"unixTimestamp"` | Encode a datetime to a unix timestamp.
Unix timestamps are represented as an integer number of seconds since the Unix epoch and usually encoded as an int32. | ### `DurationKnownEncoding` {#DurationKnownEncoding} @@ -216,6 +241,10 @@ Known encoding to use on duration enum DurationKnownEncoding ``` +| Name | Value | Description | +|------|-------|-------------| +| ISO8601 | `"ISO8601"` | ISO8601 duration | +| seconds | `"seconds"` | Encode to integer or float | ### `boolean` {#boolean} diff --git a/packages/website/versioned_docs/version-latest/standard-library/built-in-decorators.md b/packages/website/versioned_docs/version-latest/standard-library/built-in-decorators.md index d7413c6039..d30994aa58 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/built-in-decorators.md +++ b/packages/website/versioned_docs/version-latest/standard-library/built-in-decorators.md @@ -6,6 +6,9 @@ toc_max_heading_level: 3 # Built-in Decorators ## TypeSpec ### `@deprecated` {#@deprecated} +:::warning +**Deprecated**: @deprecated decorator is deprecated. Use the `#deprecated` directive instead. +::: Mark this type as deprecated. @@ -97,7 +100,7 @@ model Pet {} Specify how to encode the target type. ```typespec -@encode(encoding: string | EnumMember, encodedAs?: Scalar) +@encode(encodingOrEncodeAs: Scalar | valueof string | EnumMember, encodedAs?: Scalar) ``` #### Target @@ -107,7 +110,7 @@ Specify how to encode the target type. #### Parameters | Name | Type | Description | |------|------|-------------| -| encoding | `string \| EnumMember` | Known name of an encoding. | +| encodingOrEncodeAs | `Scalar` \| `valueof string \| EnumMember` | Known name of an encoding or a scalar type to encode as(Only for numeric types to encode as string). | | encodedAs | `Scalar` | What target type is this being encoded as. Default to string. | #### Examples @@ -127,6 +130,15 @@ scalar myDateTime extends offsetDateTime; scalar myDateTime extends unixTimestamp; ``` +##### encode numeric type to string + + +```tsp +model Pet { + @encode(string) id: int64; +} +``` + ### `@encodedName` {#@encodedName} @@ -358,6 +370,9 @@ model Pet { ### `@knownValues` {#@knownValues} +:::warning +**Deprecated**: This decorator has been deprecated. Use a named union of string literals with a string variant to achieve the same result without a decorator. +::: Provide a set of known values to a string type. ```typespec @@ -701,6 +716,9 @@ scalar LowerAlpha extends string; ### `@projectedName` {#@projectedName} +:::warning +**Deprecated**: Use `@encodedName` instead for changing the name over the wire. +::: DEPRECATED: Use `@encodedName` instead. diff --git a/packages/website/versioned_docs/version-latest/standard-library/examples.md b/packages/website/versioned_docs/version-latest/standard-library/examples.md new file mode 100644 index 0000000000..85dd97c357 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/standard-library/examples.md @@ -0,0 +1,103 @@ +--- +title: Examples +--- + +# Examples + +TypeSpec provide 2 decorators `@example` and `@opExample` to provide some examples for the types and operations. +With those decorators the examples must be provided as TypeSpec values that should be assignable to the type or operation parameter/return types. + +### Type Examples + +To give an example for a type you can use the `@example` decorator. The decorator first argument is the example value it MUST be assignable to the type it is targetting. +Additionally a title and/or description can be provided in the options. + +### Simple primitive types + +```tsp +@example(#{ name: "Max", age: 3 }) +model Pet { + name: string; + age: int32; +} +``` + +### Scalar types + +For scalar types the value must be defined with the scalar constructor. +This allows emitters to render the example in the correct protocol following the encoding of those scalar and the values set by `@encode`. + +```tsp +@example(#{ + id: "item-1", + createdAt: plainDate.fromISO("2020-01-01T00:00:00Z"), + timeout: duration.fromISO("PT1M"), +}) +model Item { + id: string; + createdAt: utcDateTime; + @encode("seconds", int32) timeout: duration; +} +``` + +### Provide title or description + +```tsp +@example(#{ name: "Max", age: 3 }, #{ title: "Pet example", description: "Simple pet example" }) +model Pet { + name: string; + age: int32; +} +``` + +### Multiple examples + +```tsp +@example(#{ name: "Max", age: 3 }, #{ title: "Minimal examples", description: "Minimal examples" }) +@example( + #{ name: "Rex", age: 8, bark: true }, + #{ title: "With optional properties", description: "Example where the pet barks" } +) +model Pet { + name: string; + age: int32; + bark?: boolean; +} +``` + +## Operation examples + +Operation example are provided with the `@opExample` decorator. Similar to the `@example` decorator the first argument is the example value however it takes both the `parameters` and `returnType` example. +The values passed to `parameters` MUST be assignable to the operation parameters and the value passed to `returnType` MUST be assignable to the operation return type. +Additionally a title and/or description can be provided in the options. + +:::note +Operation example will not validate additional properties as the applicable parameters might depend on the protocol and applied visibility. +::: + +### Simple operation parameters + +```tsp +@example(#{ parameters: #{ name: "Max", age: 3 } }) +op write(name: string, age: int32): void; +``` + +### Simple operation return types + +```tsp +@example(#{ returnType: #{ name: "Max", age: 3 } }) +op read(): { + name: string; + age: int32; +}; +``` + +### Specify title and/or description + +```tsp +@example( + #{ parameters: #{ name: "Max", age: 3 } }, + #{ title: "Simple write example", description: "Write a pet" } +) +op write(name: string, age: int32): void; +``` diff --git a/packages/website/versioned_docs/version-latest/standard-library/projected-names.md b/packages/website/versioned_docs/version-latest/standard-library/projected-names.md deleted file mode 100644 index 2c36c33857..0000000000 --- a/packages/website/versioned_docs/version-latest/standard-library/projected-names.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -id: projected-names -title: Projected Names ---- - -# Projected Names - -:::warning -The feature "Projected Names" is considered legacy and is planned for deprecation. We recommend using [Encoded Names](encoded-names.md) as a more modern alternative for modifying the name over the network. -::: - -In certain scenarios, the name you use in TypeSpec may need to be different from the name used over the network or in a specific programming language. - -## Recognized Targets - -Here is a list of recognized targets. - -- Wire: - - `json`: Set up JSON data representation - - `xml`: Set up XML data representation -- Language: - - `csharp`: Set up C# code generation - - `java`: Set up Java code generation - - `python`: Set up Python code generation - - `javascript`: Set up JavaScript code generation - - `swift` : Set up Swift code generation - - `c` : Set up C code generation -- Type: - - `client`: Set up client-side output - - `server`: Set up server-side output - -## How to Modify a Name for a Specific Target - -### Using Decorator - -To change the name of a TypeSpec entity, you can use the `@projectedName` decorator. This decorator requires 2 parameters: - -- `string` target name. Refer to the [recognized targets](#recognized-targets) -- `string` projected name. This is the name to be used in the specified target. - -Example: - -```typespec -model Foo { - // Indicate that the `expireAt` property should be named `exp` when serialized to JSON - @projectedName("json", "exp") - expireAt: string; -} -``` - -### Using Projection - -The decorator is essentially a shorthand for the `target` projection. For more complex scenarios, you might prefer to implement the projection manually. - -```typespec -model Foo { - expireAt: string; -} - -projection Foo#target { - to(targetName) { - if targetName == "json" { - self::rename("exp"); - }; - } -} -``` - -## Example - -```typespec -model CertificateAttributes { - @projectedName("json", "nbf") - @projectedName("csharp", "ValidAfter") - notBefore: int32; - - @projectedName("json", "exp") - expires: int32; - - @projectedName("client", "createdAt") - created: int32; - - updated: int32; -} -``` - - - - - - - - - - - - - - - - - - - - -
JsonTypescriptCSharp
When serialized to Json, the property uses the json projected nameTypescript doesn't specify any projected name, so it retains the model as is.The model uses the `csharp` projected names and maintains the reference to the JSON name in JsonProperty
- -```json -{ - "nbf": 1430344421, - "exp": 2208988799, - "created": 1493938289, - "updated": 1493938291 -} -``` - - - -```ts -interface Attributes { - notBefore: number; - expires: number; - createdAt: number; - updated: number; -} -``` - - - -```cs -class CertificateAttributes -{ - [JsonProperty("nbf")] - public int ValidAfter {get; set;} - - [JsonProperty("exp")] - public int Expires {get; set;} - - [JsonProperty("created")] - public int CreatedAt {get; set;} - - public int Updated {get; set;} -} -``` - -
diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encode.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encode.md index 079de2d004..5cc68e399e 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encode.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encode.md @@ -7,7 +7,7 @@ title: "[F] $encode" function $encode( context, target, - encoding, + encodingOrEncodeAs, encodedAs?): void ``` @@ -17,7 +17,7 @@ function $encode( | ------ | ------ | | `context` | [`DecoratorContext`](../interfaces/DecoratorContext.md) | | `target` | [`ModelProperty`](../interfaces/ModelProperty.md) \| [`Scalar`](../interfaces/Scalar.md) | -| `encoding` | [`Type`](../type-aliases/Type.md) | +| `encodingOrEncodeAs` | `string` \| [`Scalar`](../interfaces/Scalar.md) \| [`EnumValue`](../interfaces/EnumValue.md) | | `encodedAs`? | [`Scalar`](../interfaces/Scalar.md) | ## Returns diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$example.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$example.md index bc87a7c7f8..b64e8499d3 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$example.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$example.md @@ -18,7 +18,7 @@ function $example( | `context` | [`DecoratorContext`](../interfaces/DecoratorContext.md) | | `target` | \| [`Enum`](../interfaces/Enum.md) \| [`Model`](../interfaces/Model.md) \| [`ModelProperty`](../interfaces/ModelProperty.md) \| [`Scalar`](../interfaces/Scalar.md) \| [`Union`](../interfaces/Union.md) \| [`UnionVariant`](../interfaces/UnionVariant.md) | | `example` | `unknown` | -| `options`? | `unknown` | +| `options`? | [`ExampleOptions`](../interfaces/ExampleOptions.md) | ## Returns diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$opExample.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$opExample.md index bd52af53f8..2a5d9a3b6f 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$opExample.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$opExample.md @@ -17,8 +17,8 @@ function $opExample( | ------ | ------ | | `context` | [`DecoratorContext`](../interfaces/DecoratorContext.md) | | `target` | [`Operation`](../interfaces/Operation.md) | -| `example` | `unknown` | -| `options`? | `unknown` | +| `example` | `OperationExample` | +| `options`? | [`ExampleOptions`](../interfaces/ExampleOptions.md) | ## Returns diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/cadlTypeToJson.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/cadlTypeToJson.md index 1b7ebdf8f7..71adfa0caa 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/cadlTypeToJson.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/cadlTypeToJson.md @@ -7,9 +7,6 @@ title: "[F] cadlTypeToJson" function cadlTypeToJson(typespecType, target): [T | undefined, Diagnostic[]] ``` -Convert a TypeSpec type to a serializable Json object. -Emits diagnostics if the given type is invalid - ## Type Parameters | Type Parameter | @@ -26,3 +23,7 @@ Emits diagnostics if the given type is invalid ## Returns [`T` \| `undefined`, [`Diagnostic`](../interfaces/Diagnostic.md)[]] + +## Deprecated + +use typespecTypeToJson diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/checkFormatCadl.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/checkFormatCadl.md index 98afdd606f..353c73c399 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/checkFormatCadl.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/checkFormatCadl.md @@ -7,8 +7,6 @@ title: "[F] checkFormatCadl" function checkFormatCadl(code, prettierConfig?): Promise ``` -Check the given is correctly formatted. - ## Parameters | Parameter | Type | @@ -20,4 +18,6 @@ Check the given is correctly formatted. `Promise`<`boolean`\> -true if code is formatted correctly. +## Deprecated + +use checkFormatTypeSpec diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/createCadlLibrary.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/createCadlLibrary.md index bbc4430126..5ccd217e75 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/createCadlLibrary.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/createCadlLibrary.md @@ -7,8 +7,6 @@ title: "[F] createCadlLibrary" function createCadlLibrary(lib): TypeSpecLibrary ``` -Create a new TypeSpec library definition. - ## Type Parameters | Type Parameter | Default type | @@ -27,21 +25,6 @@ Create a new TypeSpec library definition. [`TypeSpecLibrary`](../interfaces/TypeSpecLibrary.md)<`T`, `E`, `State`\> -Library with utility functions. - -## Tutorial - -Create the lib object with `as const` to get the full typing. +## Deprecated -## Example - -```ts -const libDef = { - name: "myLib", - diagnostics: { - "my-code": {serverity: "error", messages: {default: "Foo bar"}} - }, -} as const; - -const lib = createTypeSpecLibrary(libDef); -``` +use createTypeSpecLibrary diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/isCadlValueTypeOf.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/isCadlValueTypeOf.md index b771122aa8..b52b83202b 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/isCadlValueTypeOf.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/isCadlValueTypeOf.md @@ -7,8 +7,6 @@ title: "[F] isCadlValueTypeOf" function isCadlValueTypeOf(target, expectedType): target is InferredTypeSpecValue ``` -Check if the given target is of any of the TypeSpec types. - ## Type Parameters | Type Parameter | @@ -26,4 +24,6 @@ Check if the given target is of any of the TypeSpec types. `target is InferredTypeSpecValue` -boolean if the target is of one of the allowed types. +## Deprecated + +use isTypeSpecValueTypeOf diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/setCadlNamespace.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/setCadlNamespace.md index 62f175a44e..b5968cf119 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/setCadlNamespace.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/setCadlNamespace.md @@ -7,8 +7,6 @@ title: "[F] setCadlNamespace" function setCadlNamespace(namespace, ...functions): void ``` -Set the TypeSpec namespace for that function. - ## Parameters | Parameter | Type | Description | @@ -19,3 +17,7 @@ Set the TypeSpec namespace for that function. ## Returns `void` + +## Deprecated + +use setTypeSpecNamespace diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/EncodeData.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/EncodeData.md index 100ab62251..932222fe18 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/EncodeData.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/EncodeData.md @@ -5,7 +5,7 @@ title: "[I] EncodeData" --- ## Properties -| Property | Type | -| ------ | ------ | -| `encoding` | `string` | -| `type` | [`Scalar`](Scalar.md) | +| Property | Type | Description | +| ------ | ------ | ------ | +| `encoding?` | `string` | Known encoding key. Can be undefined when `@encode(string)` is used on a numeric type. In that case it just means using the base10 decimal representation of the number. | +| `type` | [`Scalar`](Scalar.md) | - | diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibrary.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibrary.md index 27edc2fdff..ea47609b95 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibrary.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibrary.md @@ -7,13 +7,13 @@ title: "[T] CadlLibrary" type CadlLibrary: TypeSpecLibrary; ``` -## Deprecated - -Use TypeSpecLibrary - ## Type Parameters | Type Parameter | Default type | | ------ | ------ | | `T` *extends* `object` | - | | `E` *extends* `Record`<`string`, `any`\> | `Record`<`string`, `never`\> | + +## Deprecated + +Use TypeSpecLibrary diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibraryDef.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibraryDef.md index 2543af68f2..53a20225f7 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibraryDef.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/CadlLibraryDef.md @@ -7,13 +7,13 @@ title: "[T] CadlLibraryDef" type CadlLibraryDef: TypeSpecLibraryDef; ``` -## Deprecated - -Use TypeSpecLibraryDef - ## Type Parameters | Type Parameter | Default type | | ------ | ------ | | `T` *extends* `object` | - | | `E` *extends* `Record`<`string`, `any`\> | `Record`<`string`, `never`\> | + +## Deprecated + +Use TypeSpecLibraryDef diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/InferredCadlValue.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/InferredCadlValue.md index f3a694f93b..aeb68b2a2e 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/InferredCadlValue.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/type-aliases/InferredCadlValue.md @@ -7,12 +7,12 @@ title: "[T] InferredCadlValue" type InferredCadlValue: InferredTypeSpecValue; ``` -## Deprecated - -Use InferredTypeSpecValue - ## Type Parameters | Type Parameter | | ------ | | `K` *extends* [`TypeKind`](TypeKind.md) | + +## Deprecated + +Use InferredTypeSpecValue diff --git a/packages/website/versioned_sidebars/version-latest-sidebars.json b/packages/website/versioned_sidebars/version-latest-sidebars.json index 77946a3da5..baa7bc2805 100644 --- a/packages/website/versioned_sidebars/version-latest-sidebars.json +++ b/packages/website/versioned_sidebars/version-latest-sidebars.json @@ -21,15 +21,15 @@ "items": [ { "type": "category", - "label": "TypeSpec for HTTP", + "label": "TypeSpec for REST", "link": { "type": "doc", - "id": "getting-started/getting-started-http/index" + "id": "getting-started/getting-started-rest/01-setup-basic-syntax" }, "items": [ { "type": "autogenerated", - "dirName": "getting-started/getting-started-http" + "dirName": "getting-started/getting-started-rest" } ] }, @@ -91,8 +91,8 @@ "type": "autogenerated", "dirName": "standard-library/reference" }, - "standard-library/projected-names", - "standard-library/discriminated-types" + "standard-library/discriminated-types", + "standard-library/examples" ] }, { @@ -126,7 +126,8 @@ "libraries/http/operations", "libraries/http/content-types", "libraries/http/multipart", - "libraries/http/encoding" + "libraries/http/encoding", + "libraries/http/examples" ] }, { diff --git a/packages/xml/CHANGELOG.md b/packages/xml/CHANGELOG.md index cde952f58c..f282943ba5 100644 --- a/packages/xml/CHANGELOG.md +++ b/packages/xml/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog - @typespec/xml +## 0.59.0 + +### Bump dependencies + +- [#3948](https://github.com/microsoft/typespec/pull/3948) Update dependencies + +### Features + +- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string + + ## 0.58.0 ### Bump dependencies diff --git a/packages/xml/package.json b/packages/xml/package.json index e59827cac3..3eaf0b060b 100644 --- a/packages/xml/package.json +++ b/packages/xml/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/xml", - "version": "0.58.0", + "version": "0.59.0", "author": "Microsoft Corporation", "description": "TypeSpec library providing xml bindings", "homepage": "https://typespec.io",