From 0be9e8f22bb587db69bf1fc5e73effef1e2364a5 Mon Sep 17 00:00:00 2001 From: Christopher Radek <14189820+chrisradek@users.noreply.github.com> Date: Tue, 10 Sep 2024 15:45:59 -0700 Subject: [PATCH] TypeSpec 0.59 - September Release branch (#4386) Co-authored-by: Christopher Radek --- ...ashOnunsupported-auth-2024-7-13-17-3-33.md | 7 - ...nd-SemanticWalkerExit-2024-8-9-17-49-42.md | 7 - .../api-extractor-openapi-2024-8-5-13-50-8.md | 7 - .../api-extractor-trial-2024-8-4-15-12-5.md | 8 - ...ng_WebSiteFooterColor-2024-7-26-12-51-7.md | 7 - .../decorators-export-2024-7-12-2-29-0.md | 8 - .../decorators-export-2024-7-9-21-2-11.md | 16 - .../decorators-export-2024-7-9-22-3-58.md | 15 - ...ature-cli-hyperlinks-2024-7-12-20-48-20.md | 8 - .../fix-alias-expr-2024-7-12-19-19-19.md | 8 - ...variant-program-viewer-2024-8-5-13-29-8.md | 8 - ...variant-program-viewer-2024-8-5-13-29-9.md | 6 - ...fix-examples-extends-2024-7-12-19-51-31.md | 8 - ...crash-unknown-scalar-2024-7-12-22-23-57.md | 8 - ...per-model-expression-2024-7-12-17-20-15.md | 8 - .../fix-numeric-print-2024-7-9-16-3-25.md | 8 - ...ix-openapi3-union-names-2024-7-8-8-5-28.md | 7 - ...d-namespace-same-name-2024-7-9-16-22-29.md | 8 - ...und-reregistering-lsp-2024-7-2-15-43-22.md | 8 - ...erence-sub-namespace-2024-7-12-17-42-19.md | 8 - ...-regression-using-dep-2024-7-13-2-12-20.md | 8 - ...-response-doc-envelope-2024-8-3-18-12-4.md | 8 - ...-vscode-space-config-2024-6-31-22-23-57.md | 8 - ...pe-argument-tmlanguage-2024-7-5-16-16-4.md | 8 - ...ix-type-stack-mutate-2024-7-29-13-18-20.md | 6 - ...x-validate-op-params-2024-7-13-19-39-34.md | 8 - ...x-validate-op-params-2024-7-13-19-39-35.md | 8 - ...ng-op-params-take-op-2024-7-29-11-56-35.md | 6 - ...sioning-cross-ns-ref-2024-7-29-18-19-44.md | 6 - .../lsp-diag-url-2024-7-12-14-53-19.md | 8 - .../source-loader-2024-8-3-19-23-57.md | 8 - ...-checker-type-relation-2024-8-4-17-54-5.md | 8 - ...p-openapi3-add-context-2024-7-20-9-44-3.md | 7 - ...enapi3-improve-allof-2024-7-21-14-39-30.md | 7 - ...e-schemas-conversion-2024-7-12-12-55-34.md | 7 - ...relation-improvements-2024-8-6-13-13-15.md | 8 - packages/bundler/CHANGELOG.md | 7 + packages/bundler/package.json | 2 +- packages/compiler/CHANGELOG.md | 29 ++ packages/compiler/package.json | 2 +- packages/compiler/templates/scaffolding.json | 8 +- packages/eslint-plugin-typespec/CHANGELOG.md | 4 + packages/eslint-plugin-typespec/package.json | 2 +- packages/html-program-viewer/CHANGELOG.md | 8 + 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 | 4 + packages/http-server-javascript/package.json | 2 +- packages/http/CHANGELOG.md | 11 + packages/http/package.json | 2 +- packages/internal-build-utils/CHANGELOG.md | 4 + packages/internal-build-utils/package.json | 2 +- packages/json-schema/CHANGELOG.md | 11 + packages/json-schema/package.json | 2 +- packages/library-linter/CHANGELOG.md | 4 + packages/library-linter/package.json | 2 +- packages/openapi/CHANGELOG.md | 7 + packages/openapi/package.json | 2 +- packages/openapi3/CHANGELOG.md | 15 + packages/openapi3/package.json | 2 +- packages/playground/CHANGELOG.md | 8 + packages/playground/package.json | 2 +- .../prettier-plugin-typespec/CHANGELOG.md | 4 + .../prettier-plugin-typespec/package.json | 2 +- packages/protobuf/CHANGELOG.md | 7 + packages/protobuf/package.json | 2 +- packages/rest/CHANGELOG.md | 7 + packages/rest/package.json | 2 +- packages/typespec-vs/CHANGELOG.md | 4 + packages/typespec-vs/package.json | 2 +- packages/typespec-vscode/CHANGELOG.md | 4 + packages/typespec-vscode/package.json | 2 +- packages/versioning/CHANGELOG.md | 13 + packages/versioning/package.json | 2 +- packages/website/playground-versions.json | 1 + .../emitters/json-schema/reference/emitter.md | 10 + .../json-schema/reference/js-api/index.md | 1 - .../reference/js-api/variables/namespace.md | 8 - .../emitters/openapi3/reference/emitter.md | 10 + .../emitters/protobuf/reference/emitter.md | 10 + .../reference/js-api/functions/$externRef.md | 8 +- .../extending-typespec/create-decorators.md | 16 +- .../01-setup-basic-syntax.md | 345 +++++--------- .../02-operations-responses.md | 423 ++++++++++-------- .../03-handling-errors.md | 261 ++--------- .../04-common-parameters.md | 120 ++++- .../getting-started-rest/05-authentication.md | 156 ++++++- .../getting-started-rest/06-versioning.md | 160 +++++-- .../07-custom-response-models.md | 139 +++--- .../getting-started-rest/08-conclusion.md | 6 +- .../version-latest/handbook/formatter.md | 33 ++ .../introduction/installation.md | 14 +- .../reference/js-api/functions/$onValidate.md | 18 - .../functions/addQueryParamsToUriTemplate.md | 19 + .../functions/getUriTemplatePathParam.md | 18 + .../libraries/http/reference/js-api/index.md | 3 +- .../functions/checkDuplicateTypeName.md | 14 +- .../js-api/functions/getExtensions.md | 10 +- .../js-api/functions/getExternalDocs.md | 10 +- .../reference/js-api/functions/getInfo.md | 10 +- .../js-api/functions/getOperationId.md | 8 +- .../js-api/functions/resolveOperationId.md | 10 +- .../js-api/functions/setExtension.md | 14 +- .../reference/js-api/functions/setInfo.md | 12 +- .../openapi/reference/js-api/index.md | 8 +- .../reference/js-api/interfaces/Contact.md | 2 + .../js-api/interfaces/ExternalDocs.md | 10 +- .../reference/js-api/interfaces/License.md | 2 + .../type-aliases/DefaultResponseDecorator.md | 31 ++ .../js-api/type-aliases/ExtensionDecorator.md | 31 ++ .../js-api/type-aliases/ExtensionKey.md | 3 + .../type-aliases/ExternalDocsDecorator.md | 30 ++ .../js-api/type-aliases/InfoDecorator.md | 23 + .../reference/js-api/variables/namespace.md | 8 - .../reference/js-api/functions/$onValidate.md | 18 - .../libraries/rest/reference/js-api/index.md | 3 +- .../rest/reference/js-api/variables/$lib.md | 27 ++ .../reference/js-api/variables/namespace.md | 8 - .../reference/js-api/functions/$attribute.md | 2 + .../xml/reference/js-api/functions/$name.md | 3 + .../libraries/xml/reference/js-api/index.md | 9 + .../js-api/interfaces/XmlEncodeData.md | 6 +- .../js-api/interfaces/XmlNamespace.md | 10 +- .../js-api/type-aliases/AttributeDecorator.md | 46 ++ .../js-api/type-aliases/NameDecorator.md | 42 ++ .../type-aliases/NsDeclarationsDecorator.md | 21 + .../js-api/type-aliases/NsDecorator.md | 53 +++ .../js-api/type-aliases/UnwrappedDecorator.md | 80 ++++ .../xml/reference/js-api/variables/$lib.md | 25 ++ .../release-notes/release-2024-09-10.md | 62 +++ .../standard-library/examples.md | 6 +- .../js-api/functions/$encodedName.md | 25 -- .../reference/js-api/index.md | 2 +- .../interfaces/DecoratorImplementations.md | 21 + .../js-api/interfaces/ProcessedLog.md | 13 +- packages/xml/CHANGELOG.md | 7 + packages/xml/package.json | 2 +- 138 files changed, 1751 insertions(+), 1243 deletions(-) delete mode 100644 .chronus/changes/CrashOnunsupported-auth-2024-7-13-17-3-33.md delete mode 100644 .chronus/changes/almend-SemanticWalkerExit-2024-8-9-17-49-42.md delete mode 100644 .chronus/changes/api-extractor-openapi-2024-8-5-13-50-8.md delete mode 100644 .chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md delete mode 100644 .chronus/changes/azhang_WebSiteFooterColor-2024-7-26-12-51-7.md delete mode 100644 .chronus/changes/decorators-export-2024-7-12-2-29-0.md delete mode 100644 .chronus/changes/decorators-export-2024-7-9-21-2-11.md delete mode 100644 .chronus/changes/decorators-export-2024-7-9-22-3-58.md delete mode 100644 .chronus/changes/feature-cli-hyperlinks-2024-7-12-20-48-20.md delete mode 100644 .chronus/changes/fix-alias-expr-2024-7-12-19-19-19.md delete mode 100644 .chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-8.md delete mode 100644 .chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-9.md delete mode 100644 .chronus/changes/fix-examples-extends-2024-7-12-19-51-31.md delete mode 100644 .chronus/changes/fix-json-schema-crash-unknown-scalar-2024-7-12-22-23-57.md delete mode 100644 .chronus/changes/fix-mapper-model-expression-2024-7-12-17-20-15.md delete mode 100644 .chronus/changes/fix-numeric-print-2024-7-9-16-3-25.md delete mode 100644 .chronus/changes/fix-openapi3-union-names-2024-7-8-8-5-28.md delete mode 100644 .chronus/changes/fix-playground-namespace-same-name-2024-7-9-16-22-29.md delete mode 100644 .chronus/changes/fix-playground-reregistering-lsp-2024-7-2-15-43-22.md delete mode 100644 .chronus/changes/fix-reference-sub-namespace-2024-7-12-17-42-19.md delete mode 100644 .chronus/changes/fix-regression-using-dep-2024-7-13-2-12-20.md delete mode 100644 .chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md delete mode 100644 .chronus/changes/fix-stop-respecting-vscode-space-config-2024-6-31-22-23-57.md delete mode 100644 .chronus/changes/fix-type-argument-tmlanguage-2024-7-5-16-16-4.md delete mode 100644 .chronus/changes/fix-type-stack-mutate-2024-7-29-13-18-20.md delete mode 100644 .chronus/changes/fix-validate-op-params-2024-7-13-19-39-34.md delete mode 100644 .chronus/changes/fix-validate-op-params-2024-7-13-19-39-35.md delete mode 100644 .chronus/changes/fix-validate-versioning-op-params-take-op-2024-7-29-11-56-35.md delete mode 100644 .chronus/changes/fix-versioning-cross-ns-ref-2024-7-29-18-19-44.md delete mode 100644 .chronus/changes/lsp-diag-url-2024-7-12-14-53-19.md delete mode 100644 .chronus/changes/source-loader-2024-8-3-19-23-57.md delete mode 100644 .chronus/changes/split-checker-type-relation-2024-8-4-17-54-5.md delete mode 100644 .chronus/changes/tsp-openapi3-add-context-2024-7-20-9-44-3.md delete mode 100644 .chronus/changes/tsp-openapi3-improve-allof-2024-7-21-14-39-30.md delete mode 100644 .chronus/changes/tsp-openapi3-improve-schemas-conversion-2024-7-12-12-55-34.md delete mode 100644 .chronus/changes/type-relation-improvements-2024-8-6-13-13-15.md delete mode 100644 packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/namespace.md delete mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$onValidate.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/addQueryParamsToUriTemplate.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getUriTemplatePathParam.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/DefaultResponseDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExternalDocsDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/InfoDecorator.md delete mode 100644 packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/variables/namespace.md delete mode 100644 packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/functions/$onValidate.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/$lib.md delete mode 100644 packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/namespace.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/AttributeDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NameDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDeclarationsDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/UnwrappedDecorator.md create mode 100644 packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/variables/$lib.md create mode 100644 packages/website/versioned_docs/version-latest/release-notes/release-2024-09-10.md delete mode 100644 packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encodedName.md create mode 100644 packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/DecoratorImplementations.md diff --git a/.chronus/changes/CrashOnunsupported-auth-2024-7-13-17-3-33.md b/.chronus/changes/CrashOnunsupported-auth-2024-7-13-17-3-33.md deleted file mode 100644 index 7e85e02ba..000000000 --- a/.chronus/changes/CrashOnunsupported-auth-2024-7-13-17-3-33.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fix Bug for OpenAPI 3 Emitter crash on `@useAuth({})` \ No newline at end of file diff --git a/.chronus/changes/almend-SemanticWalkerExit-2024-8-9-17-49-42.md b/.chronus/changes/almend-SemanticWalkerExit-2024-8-9-17-49-42.md deleted file mode 100644 index 5527dba27..000000000 --- a/.chronus/changes/almend-SemanticWalkerExit-2024-8-9-17-49-42.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix Semantic walker doesn't fire exitOperation or exitModelProperty \ No newline at end of file diff --git a/.chronus/changes/api-extractor-openapi-2024-8-5-13-50-8.md b/.chronus/changes/api-extractor-openapi-2024-8-5-13-50-8.md deleted file mode 100644 index 7744eddc2..000000000 --- a/.chronus/changes/api-extractor-openapi-2024-8-5-13-50-8.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/openapi" ---- - -Add api extractor setup \ No newline at end of file diff --git a/.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md b/.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md deleted file mode 100644 index b288acc18..000000000 --- a/.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/xml" ---- - -Setup api extractor for xml library diff --git a/.chronus/changes/azhang_WebSiteFooterColor-2024-7-26-12-51-7.md b/.chronus/changes/azhang_WebSiteFooterColor-2024-7-26-12-51-7.md deleted file mode 100644 index 5f520d69b..000000000 --- a/.chronus/changes/azhang_WebSiteFooterColor-2024-7-26-12-51-7.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/playground" ---- - -Accessibility, increase footer contrast \ No newline at end of file diff --git a/.chronus/changes/decorators-export-2024-7-12-2-29-0.md b/.chronus/changes/decorators-export-2024-7-12-2-29-0.md deleted file mode 100644 index 173235ab8..000000000 --- a/.chronus/changes/decorators-export-2024-7-12-2-29-0.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/bundler" ---- - -Allow bundling libraries that don't import their `main` file from the TypeSpec diff --git a/.chronus/changes/decorators-export-2024-7-9-21-2-11.md b/.chronus/changes/decorators-export-2024-7-9-21-2-11.md deleted file mode 100644 index 6d9b8192e..000000000 --- a/.chronus/changes/decorators-export-2024-7-9-21-2-11.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Add new way to define decorator implementation with `$decorators` export. -```ts -export const $decorators = { - "TypeSpec.OpenAPI": { - useRef: $useRef, - oneOf: $oneOf, - }, -}; -``` diff --git a/.chronus/changes/decorators-export-2024-7-9-22-3-58.md b/.chronus/changes/decorators-export-2024-7-9-22-3-58.md deleted file mode 100644 index f03bb3e78..000000000 --- a/.chronus/changes/decorators-export-2024-7-9-22-3-58.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/http" - - "@typespec/json-schema" - - "@typespec/openapi" - - "@typespec/openapi3" - - "@typespec/protobuf" - - "@typespec/rest" - - "@typespec/versioning" - - "@typespec/xml" ---- - -Internals: Migrate to new api for declaring decorator implementation diff --git a/.chronus/changes/feature-cli-hyperlinks-2024-7-12-20-48-20.md b/.chronus/changes/feature-cli-hyperlinks-2024-7-12-20-48-20.md deleted file mode 100644 index bfd90d859..000000000 --- a/.chronus/changes/feature-cli-hyperlinks-2024-7-12-20-48-20.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Diagnostics logged to the terminal now have a clickable hyperlink to the diagnostic documentation url if applicable. diff --git a/.chronus/changes/fix-alias-expr-2024-7-12-19-19-19.md b/.chronus/changes/fix-alias-expr-2024-7-12-19-19-19.md deleted file mode 100644 index e6a69e375..000000000 --- a/.chronus/changes/fix-alias-expr-2024-7-12-19-19-19.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix model expression defined in alias will resolve its namespace from the namespace where the alias was declared diff --git a/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-8.md b/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-8.md deleted file mode 100644 index 024e33928..000000000 --- a/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-8.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/html-program-viewer" ---- - -Fix crash when using anonymous union variant diff --git a/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-9.md b/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-9.md deleted file mode 100644 index d64a80d47..000000000 --- a/.chronus/changes/fix-anon-union-variant-program-viewer-2024-8-5-13-29-9.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/playground" ---- diff --git a/.chronus/changes/fix-examples-extends-2024-7-12-19-51-31.md b/.chronus/changes/fix-examples-extends-2024-7-12-19-51-31.md deleted file mode 100644 index 34cfd368a..000000000 --- a/.chronus/changes/fix-examples-extends-2024-7-12-19-51-31.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix examples with models using `extends` diff --git a/.chronus/changes/fix-json-schema-crash-unknown-scalar-2024-7-12-22-23-57.md b/.chronus/changes/fix-json-schema-crash-unknown-scalar-2024-7-12-22-23-57.md deleted file mode 100644 index aab11384e..000000000 --- a/.chronus/changes/fix-json-schema-crash-unknown-scalar-2024-7-12-22-23-57.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/json-schema" ---- - -Stop json schema from crashing on unknown scalar and handle `unixTimestamp32` diff --git a/.chronus/changes/fix-mapper-model-expression-2024-7-12-17-20-15.md b/.chronus/changes/fix-mapper-model-expression-2024-7-12-17-20-15.md deleted file mode 100644 index 2bf58aa59..000000000 --- a/.chronus/changes/fix-mapper-model-expression-2024-7-12-17-20-15.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix: Model and union expression in template were not considered as template instances diff --git a/.chronus/changes/fix-numeric-print-2024-7-9-16-3-25.md b/.chronus/changes/fix-numeric-print-2024-7-9-16-3-25.md deleted file mode 100644 index 3c154e8fe..000000000 --- a/.chronus/changes/fix-numeric-print-2024-7-9-16-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" ---- - -Fix numeric 0 stringify producing 0.0 diff --git a/.chronus/changes/fix-openapi3-union-names-2024-7-8-8-5-28.md b/.chronus/changes/fix-openapi3-union-names-2024-7-8-8-5-28.md deleted file mode 100644 index 1e12651d0..000000000 --- a/.chronus/changes/fix-openapi3-union-names-2024-7-8-8-5-28.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fix OpenAPI3 union names when declared within a namespace diff --git a/.chronus/changes/fix-playground-namespace-same-name-2024-7-9-16-22-29.md b/.chronus/changes/fix-playground-namespace-same-name-2024-7-9-16-22-29.md deleted file mode 100644 index d61377094..000000000 --- a/.chronus/changes/fix-playground-namespace-same-name-2024-7-9-16-22-29.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/html-program-viewer" ---- - -Fix namespace with the same name conflicting in the tree navigation diff --git a/.chronus/changes/fix-playground-reregistering-lsp-2024-7-2-15-43-22.md b/.chronus/changes/fix-playground-reregistering-lsp-2024-7-2-15-43-22.md deleted file mode 100644 index 432382f01..000000000 --- a/.chronus/changes/fix-playground-reregistering-lsp-2024-7-2-15-43-22.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/playground" ---- - -Fix: Reloading the playground will not register the typespec language server diff --git a/.chronus/changes/fix-reference-sub-namespace-2024-7-12-17-42-19.md b/.chronus/changes/fix-reference-sub-namespace-2024-7-12-17-42-19.md deleted file mode 100644 index 0dfe52b31..000000000 --- a/.chronus/changes/fix-reference-sub-namespace-2024-7-12-17-42-19.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/versioning" ---- - -Fix error when trying to reference types from another sub namespace of a versioned namespace diff --git a/.chronus/changes/fix-regression-using-dep-2024-7-13-2-12-20.md b/.chronus/changes/fix-regression-using-dep-2024-7-13-2-12-20.md deleted file mode 100644 index a609758d9..000000000 --- a/.chronus/changes/fix-regression-using-dep-2024-7-13-2-12-20.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/versioning" ---- - -Fix regression using dep diff --git a/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md b/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md deleted file mode 100644 index 07a087958..000000000 --- a/.chronus/changes/fix-response-doc-envelope-2024-8-3-18-12-4.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/http" ---- - -Use user provided description of model if model has a status code property(detect it as an response envelope) diff --git a/.chronus/changes/fix-stop-respecting-vscode-space-config-2024-6-31-22-23-57.md b/.chronus/changes/fix-stop-respecting-vscode-space-config-2024-6-31-22-23-57.md deleted file mode 100644 index ca001e0ea..000000000 --- a/.chronus/changes/fix-stop-respecting-vscode-space-config-2024-6-31-22-23-57.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -IDE: Formatting command will use prettier config if provided over the editor's configuration. diff --git a/.chronus/changes/fix-type-argument-tmlanguage-2024-7-5-16-16-4.md b/.chronus/changes/fix-type-argument-tmlanguage-2024-7-5-16-16-4.md deleted file mode 100644 index e60217f34..000000000 --- a/.chronus/changes/fix-type-argument-tmlanguage-2024-7-5-16-16-4.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -Fix tmlanguage for named type argument in type reference. diff --git a/.chronus/changes/fix-type-stack-mutate-2024-7-29-13-18-20.md b/.chronus/changes/fix-type-stack-mutate-2024-7-29-13-18-20.md deleted file mode 100644 index 65426bb01..000000000 --- a/.chronus/changes/fix-type-stack-mutate-2024-7-29-13-18-20.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/versioning" ---- - diff --git a/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-34.md b/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-34.md deleted file mode 100644 index 6bc7f2b20..000000000 --- a/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-34.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/versioning" ---- - -Add validation to make sure operation params reference models available in the current version diff --git a/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-35.md b/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-35.md deleted file mode 100644 index a6c2b6f92..000000000 --- a/.chronus/changes/fix-validate-op-params-2024-7-13-19-39-35.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/versioning" ---- - -Add validation to make sure types referencing array in union types have compatible versioning. diff --git a/.chronus/changes/fix-validate-versioning-op-params-take-op-2024-7-29-11-56-35.md b/.chronus/changes/fix-validate-versioning-op-params-take-op-2024-7-29-11-56-35.md deleted file mode 100644 index 65426bb01..000000000 --- a/.chronus/changes/fix-validate-versioning-op-params-take-op-2024-7-29-11-56-35.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/versioning" ---- - diff --git a/.chronus/changes/fix-versioning-cross-ns-ref-2024-7-29-18-19-44.md b/.chronus/changes/fix-versioning-cross-ns-ref-2024-7-29-18-19-44.md deleted file mode 100644 index 65426bb01..000000000 --- a/.chronus/changes/fix-versioning-cross-ns-ref-2024-7-29-18-19-44.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/versioning" ---- - diff --git a/.chronus/changes/lsp-diag-url-2024-7-12-14-53-19.md b/.chronus/changes/lsp-diag-url-2024-7-12-14-53-19.md deleted file mode 100644 index 7e26cde6e..000000000 --- a/.chronus/changes/lsp-diag-url-2024-7-12-14-53-19.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Diagnostic code in IDE now link to the linter rule documentation url if applicable diff --git a/.chronus/changes/source-loader-2024-8-3-19-23-57.md b/.chronus/changes/source-loader-2024-8-3-19-23-57.md deleted file mode 100644 index 4fc7489e4..000000000 --- a/.chronus/changes/source-loader-2024-8-3-19-23-57.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: fix -packages: - - "@typespec/compiler" ---- - -API: Extract source resolution logic into its own source loader diff --git a/.chronus/changes/split-checker-type-relation-2024-8-4-17-54-5.md b/.chronus/changes/split-checker-type-relation-2024-8-4-17-54-5.md deleted file mode 100644 index ae174cadc..000000000 --- a/.chronus/changes/split-checker-type-relation-2024-8-4-17-54-5.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: internal -packages: - - "@typespec/compiler" ---- - -Refactor checker: Split type relation logic diff --git a/.chronus/changes/tsp-openapi3-add-context-2024-7-20-9-44-3.md b/.chronus/changes/tsp-openapi3-add-context-2024-7-20-9-44-3.md deleted file mode 100644 index cdd91dc72..000000000 --- a/.chronus/changes/tsp-openapi3-add-context-2024-7-20-9-44-3.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Fixes issue in tsp-openapi3 that resulted in component schemas and parameters with the same name being merged into a single TypeSpec data type. \ No newline at end of file diff --git a/.chronus/changes/tsp-openapi3-improve-allof-2024-7-21-14-39-30.md b/.chronus/changes/tsp-openapi3-improve-allof-2024-7-21-14-39-30.md deleted file mode 100644 index 9e1536b51..000000000 --- a/.chronus/changes/tsp-openapi3-improve-allof-2024-7-21-14-39-30.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Improves tsp-openapi3 model generation from schemas utilizing allOf. Models will now extend an allOf member if it is a schema reference and the only member with a discriminator. Other members will be spread into the model if defined as a schema reference, or have their properties treated as top-level properties if they are an inline-schema. \ No newline at end of file diff --git a/.chronus/changes/tsp-openapi3-improve-schemas-conversion-2024-7-12-12-55-34.md b/.chronus/changes/tsp-openapi3-improve-schemas-conversion-2024-7-12-12-55-34.md deleted file mode 100644 index ce9b70716..000000000 --- a/.chronus/changes/tsp-openapi3-improve-schemas-conversion-2024-7-12-12-55-34.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/openapi3" ---- - -Updates tsp-openapi3 conversion of OpenAPI3 component schemas to improve handling of enums, unions, scalars, and aliases. \ No newline at end of file diff --git a/.chronus/changes/type-relation-improvements-2024-8-6-13-13-15.md b/.chronus/changes/type-relation-improvements-2024-8-6-13-13-15.md deleted file mode 100644 index f1937efc8..000000000 --- a/.chronus/changes/type-relation-improvements-2024-8-6-13-13-15.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking -changeKind: feature -packages: - - "@typespec/compiler" ---- - -Improvements to type relation errors: Show stack when it happens in a nested property otherwise show up in the correct location. diff --git a/packages/bundler/CHANGELOG.md b/packages/bundler/CHANGELOG.md index 13dbbc004..3562788cd 100644 --- a/packages/bundler/CHANGELOG.md +++ b/packages/bundler/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/bundler +## 0.1.7 + +### Bug Fixes + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Allow bundling libraries that don't import their `main` file from the TypeSpec + + ## 0.1.6 ### Bump dependencies diff --git a/packages/bundler/package.json b/packages/bundler/package.json index 23a9dda83..377d86b1b 100644 --- a/packages/bundler/package.json +++ b/packages/bundler/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/bundler", - "version": "0.1.6", + "version": "0.1.7", "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 72fdadeae..8941b1145 100644 --- a/packages/compiler/CHANGELOG.md +++ b/packages/compiler/CHANGELOG.md @@ -1,5 +1,34 @@ # Change Log - @typespec/compiler +## 0.60.0 + +### Bug Fixes + +- [#4381](https://github.com/microsoft/typespec/pull/4381) Fix Semantic walker doesn't fire exitOperation or exitModelProperty +- [#4146](https://github.com/microsoft/typespec/pull/4146) Fix model expression defined in alias will resolve its namespace from the namespace where the alias was declared +- [#4147](https://github.com/microsoft/typespec/pull/4147) Fix examples with models using `extends` +- [#4144](https://github.com/microsoft/typespec/pull/4144) Fix: Model and union expression in template were not considered as template instances +- [#4135](https://github.com/microsoft/typespec/pull/4135) Fix numeric 0 stringify producing 0.0 +- [#4064](https://github.com/microsoft/typespec/pull/4064) IDE: Formatting command will use prettier config if provided over the editor's configuration. +- [#4089](https://github.com/microsoft/typespec/pull/4089) Fix tmlanguage for named type argument in type reference. +- [#4324](https://github.com/microsoft/typespec/pull/4324) API: Extract source resolution logic into its own source loader + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Add new way to define decorator implementation with `$decorators` export. +```ts +export const $decorators = { + "TypeSpec.OpenAPI": { + useRef: $useRef, + oneOf: $oneOf, + }, +}; +``` +- [#4148](https://github.com/microsoft/typespec/pull/4148) Diagnostics logged to the terminal now have a clickable hyperlink to the diagnostic documentation url if applicable. +- [#4141](https://github.com/microsoft/typespec/pull/4141) Diagnostic code in IDE now link to the linter rule documentation url if applicable +- [#4357](https://github.com/microsoft/typespec/pull/4357) Improvements to type relation errors: Show stack when it happens in a nested property otherwise show up in the correct location. + + ## 0.59.1 ### Bug Fixes diff --git a/packages/compiler/package.json b/packages/compiler/package.json index db6795cc4..4258e5be2 100644 --- a/packages/compiler/package.json +++ b/packages/compiler/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/compiler", - "version": "0.59.1", + "version": "0.60.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 42f150f51..a530b056d 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.59.1" + "compilerVersion": "0.60.0" }, "rest": { "title": "Generic REST API", "description": "Create a project representing a generic REST API", - "compilerVersion": "0.59.1", + "compilerVersion": "0.60.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.59.1", + "compilerVersion": "0.60.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.59.1", + "compilerVersion": "0.60.0", "libraries": [], "files": [ { diff --git a/packages/eslint-plugin-typespec/CHANGELOG.md b/packages/eslint-plugin-typespec/CHANGELOG.md index 8767d6511..86aaa1178 100644 --- a/packages/eslint-plugin-typespec/CHANGELOG.md +++ b/packages/eslint-plugin-typespec/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - @typespec/eslint-plugin +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bump dependencies diff --git a/packages/eslint-plugin-typespec/package.json b/packages/eslint-plugin-typespec/package.json index dd4bd403b..05c2f4782 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.59.0", + "version": "0.60.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 90525262c..bd64a9797 100644 --- a/packages/html-program-viewer/CHANGELOG.md +++ b/packages/html-program-viewer/CHANGELOG.md @@ -1,5 +1,13 @@ # Change Log - @typespec/html-program-viewer +## 0.60.0 + +### Bug Fixes + +- [#4353](https://github.com/microsoft/typespec/pull/4353) Fix crash when using anonymous union variant +- [#4136](https://github.com/microsoft/typespec/pull/4136) Fix namespace with the same name conflicting in the tree navigation + + ## 0.59.0 ### Bump dependencies diff --git a/packages/html-program-viewer/package.json b/packages/html-program-viewer/package.json index b88f38f2b..70b725b14 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.59.0", + "version": "0.60.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 3e2f073da..c2f9e93cf 100644 --- a/packages/http-server-csharp/CHANGELOG.md +++ b/packages/http-server-csharp/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - @typespec/http-server-csharp +## 0.58.0-alpha.3 + +No changes, version bump only. + ## 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 dd19fc20c..69fa2a750 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.2", + "version": "0.58.0-alpha.3", "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 00c90b8c6..b502fb05c 100644 --- a/packages/http-server-javascript/CHANGELOG.md +++ b/packages/http-server-javascript/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog - @typespec/http-server-javascript +## 0.58.0-alpha.3 + +No changes, version bump only. + ## 0.58.0-alpha.2 ### Bug Fixes diff --git a/packages/http-server-javascript/package.json b/packages/http-server-javascript/package.json index 0931baf3c..9b2c55384 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.2", + "version": "0.58.0-alpha.3", "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 d082a0fe9..6e09e7ed1 100644 --- a/packages/http/CHANGELOG.md +++ b/packages/http/CHANGELOG.md @@ -1,5 +1,16 @@ # Change Log - @typespec/http +## 0.60.0 + +### Bug Fixes + +- [#4322](https://github.com/microsoft/typespec/pull/4322) Use user provided description of model if model has a status code property(detect it as an response envelope) + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.1 ### Bug Fixes diff --git a/packages/http/package.json b/packages/http/package.json index 92c6e0b54..7c7d422d1 100644 --- a/packages/http/package.json +++ b/packages/http/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/http", - "version": "0.59.1", + "version": "0.60.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 775c5915d..8c647e228 100644 --- a/packages/internal-build-utils/CHANGELOG.md +++ b/packages/internal-build-utils/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - @typespec/internal-build-utils +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bump dependencies diff --git a/packages/internal-build-utils/package.json b/packages/internal-build-utils/package.json index 0e618fafc..fa528b940 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.59.0", + "version": "0.60.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 047c9e097..aa44aaa29 100644 --- a/packages/json-schema/CHANGELOG.md +++ b/packages/json-schema/CHANGELOG.md @@ -1,5 +1,16 @@ # Change Log - @typespec/json-schema +## 0.60.0 + +### Bug Fixes + +- [#4150](https://github.com/microsoft/typespec/pull/4150) Stop json schema from crashing on unknown scalar and handle `unixTimestamp32` + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.0 ### Bump dependencies diff --git a/packages/json-schema/package.json b/packages/json-schema/package.json index f22a278ef..b1b1bb11a 100644 --- a/packages/json-schema/package.json +++ b/packages/json-schema/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/json-schema", - "version": "0.59.0", + "version": "0.60.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 4be777700..9a36b88c3 100644 --- a/packages/library-linter/CHANGELOG.md +++ b/packages/library-linter/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - @typespec/library-linter +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bump dependencies diff --git a/packages/library-linter/package.json b/packages/library-linter/package.json index 7b4f779c2..5c4e5d095 100644 --- a/packages/library-linter/package.json +++ b/packages/library-linter/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/library-linter", - "version": "0.59.0", + "version": "0.60.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 ed50e1951..6a276e46a 100644 --- a/packages/openapi/CHANGELOG.md +++ b/packages/openapi/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/openapi +## 0.60.0 + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.0 ### Bump dependencies diff --git a/packages/openapi/package.json b/packages/openapi/package.json index 831b3f62b..7d8f7b166 100644 --- a/packages/openapi/package.json +++ b/packages/openapi/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/openapi", - "version": "0.59.0", + "version": "0.60.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 aa12169fa..8e1747696 100644 --- a/packages/openapi3/CHANGELOG.md +++ b/packages/openapi3/CHANGELOG.md @@ -1,5 +1,20 @@ # Change Log - @typespec/openapi3 +## 0.60.0 + +### Bug Fixes + +- [#4133](https://github.com/microsoft/typespec/pull/4133) Fix Bug for OpenAPI 3 Emitter crash on `@useAuth({})` +- [#4123](https://github.com/microsoft/typespec/pull/4123) Fix OpenAPI3 union names when declared within a namespace +- [#4216](https://github.com/microsoft/typespec/pull/4216) Fixes issue in tsp-openapi3 that resulted in component schemas and parameters with the same name being merged into a single TypeSpec data type. +- [#4232](https://github.com/microsoft/typespec/pull/4232) Improves tsp-openapi3 model generation from schemas utilizing allOf. Models will now extend an allOf member if it is a schema reference and the only member with a discriminator. Other members will be spread into the model if defined as a schema reference, or have their properties treated as top-level properties if they are an inline-schema. +- [#4149](https://github.com/microsoft/typespec/pull/4149) Updates tsp-openapi3 conversion of OpenAPI3 component schemas to improve handling of enums, unions, scalars, and aliases. + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.1 ### Bug Fixes diff --git a/packages/openapi3/package.json b/packages/openapi3/package.json index ee49a9812..284c0b6e5 100644 --- a/packages/openapi3/package.json +++ b/packages/openapi3/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/openapi3", - "version": "0.59.1", + "version": "0.60.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 ffe08c8ff..d3051356e 100644 --- a/packages/playground/CHANGELOG.md +++ b/packages/playground/CHANGELOG.md @@ -1,5 +1,13 @@ # Change Log - @typespec/playground +## 0.4.2 + +### Bug Fixes + +- [#4276](https://github.com/microsoft/typespec/pull/4276) Accessibility, increase footer contrast +- [#4081](https://github.com/microsoft/typespec/pull/4081) Fix: Reloading the playground will not register the typespec language server + + ## 0.4.1 ### Bump dependencies diff --git a/packages/playground/package.json b/packages/playground/package.json index ab013d29f..1da8b7077 100644 --- a/packages/playground/package.json +++ b/packages/playground/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/playground", - "version": "0.4.1", + "version": "0.4.2", "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 93ee055ce..97ba60e8c 100644 --- a/packages/prettier-plugin-typespec/CHANGELOG.md +++ b/packages/prettier-plugin-typespec/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - @typespec/prettier-plugin-typespec +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bump dependencies diff --git a/packages/prettier-plugin-typespec/package.json b/packages/prettier-plugin-typespec/package.json index b2ef88f5b..e2317a928 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.59.0", + "version": "0.60.0", "description": "", "main": "dist/index.js", "scripts": { diff --git a/packages/protobuf/CHANGELOG.md b/packages/protobuf/CHANGELOG.md index a4f5fa1b2..af6a5194f 100644 --- a/packages/protobuf/CHANGELOG.md +++ b/packages/protobuf/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/protobuf +## 0.60.0 + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.0 ### Bug Fixes diff --git a/packages/protobuf/package.json b/packages/protobuf/package.json index f0d200fe8..93c5121b5 100644 --- a/packages/protobuf/package.json +++ b/packages/protobuf/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/protobuf", - "version": "0.59.0", + "version": "0.60.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 d3e69cc02..afa7e4de8 100644 --- a/packages/rest/CHANGELOG.md +++ b/packages/rest/CHANGELOG.md @@ -1,5 +1,12 @@ # Change Log - @typespec/rest +## 0.60.0 + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.1 ### Bug Fixes diff --git a/packages/rest/package.json b/packages/rest/package.json index 6a807e816..e703922de 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/rest", - "version": "0.59.1", + "version": "0.60.0", "author": "Microsoft Corporation", "description": "TypeSpec REST protocol binding", "homepage": "https://typespec.io", diff --git a/packages/typespec-vs/CHANGELOG.md b/packages/typespec-vs/CHANGELOG.md index c0eb5932e..14194e139 100644 --- a/packages/typespec-vs/CHANGELOG.md +++ b/packages/typespec-vs/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - typespec-vs +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bug Fixes diff --git a/packages/typespec-vs/package.json b/packages/typespec-vs/package.json index 3f40aad45..90cb9a96c 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.59.0", + "version": "0.60.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 6660c204e..401cdfffb 100644 --- a/packages/typespec-vscode/CHANGELOG.md +++ b/packages/typespec-vscode/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log - typespec-vscode +## 0.60.0 + +No changes, version bump only. + ## 0.59.0 ### Bump dependencies diff --git a/packages/typespec-vscode/package.json b/packages/typespec-vscode/package.json index 0d15c964f..3c6845fbc 100644 --- a/packages/typespec-vscode/package.json +++ b/packages/typespec-vscode/package.json @@ -1,6 +1,6 @@ { "name": "typespec-vscode", - "version": "0.59.0", + "version": "0.60.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 c5a7c1376..69ebdb65c 100644 --- a/packages/versioning/CHANGELOG.md +++ b/packages/versioning/CHANGELOG.md @@ -1,5 +1,18 @@ # Change Log - @typespec/versioning +## 0.60.0 + +### Bug Fixes + +- [#4145](https://github.com/microsoft/typespec/pull/4145) Fix error when trying to reference types from another sub namespace of a versioned namespace +- [#4179](https://github.com/microsoft/typespec/pull/4179) Add validation to make sure operation params reference models available in the current version +- [#4179](https://github.com/microsoft/typespec/pull/4179) Add validation to make sure types referencing array in union types have compatible versioning. + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.0 ### Bug Fixes diff --git a/packages/versioning/package.json b/packages/versioning/package.json index 9768b35b0..4befc0aed 100644 --- a/packages/versioning/package.json +++ b/packages/versioning/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/versioning", - "version": "0.59.0", + "version": "0.60.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 e7f24cd81..fcab092f2 100644 --- a/packages/website/playground-versions.json +++ b/packages/website/playground-versions.json @@ -1,4 +1,5 @@ [ + "0.60.x", "0.59.x", "0.58.x", "0.57.x", diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/emitter.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/emitter.md index a9d77988d..fad990667 100644 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/emitter.md +++ b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/emitter.md @@ -21,6 +21,16 @@ emit: - "@typespec/json-schema" ``` +The config can be extended with options as follows: + +```yaml +emit: + - "@typespec/json-schema" +options: + "@typespec/json-schema": + option: value +``` + ## Emitter options ### `file-type` 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 a1064819a..d815396a4 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 @@ -21,7 +21,6 @@ title: "[P] JS API" - [$flags](variables/$flags.md) - [$lib](variables/$lib.md) - [EmitterOptionsSchema](variables/EmitterOptionsSchema.md) -- [namespace](variables/namespace.md) ## Functions diff --git a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/namespace.md b/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/namespace.md deleted file mode 100644 index 1787cce0c..000000000 --- a/packages/website/versioned_docs/version-latest/emitters/json-schema/reference/js-api/variables/namespace.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -jsApi: true -title: "[V] namespace" - ---- -```ts -const namespace: "TypeSpec.JsonSchema" = "TypeSpec.JsonSchema"; -``` diff --git a/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/emitter.md b/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/emitter.md index b9f4be9c9..53827c1e3 100644 --- a/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/emitter.md +++ b/packages/website/versioned_docs/version-latest/emitters/openapi3/reference/emitter.md @@ -21,6 +21,16 @@ emit: - "@typespec/openapi3" ``` +The config can be extended with options as follows: + +```yaml +emit: + - "@typespec/openapi3" +options: + "@typespec/openapi3": + option: value +``` + ## Emitter options ### `file-type` diff --git a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/emitter.md b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/emitter.md index 22e256a81..b9c8fc245 100644 --- a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/emitter.md +++ b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/emitter.md @@ -21,6 +21,16 @@ emit: - "@typespec/protobuf" ``` +The config can be extended with options as follows: + +```yaml +emit: + - "@typespec/protobuf" +options: + "@typespec/protobuf": + option: value +``` + ## Emitter options ### `noEmit` diff --git a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$externRef.md b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$externRef.md index d558e14ca..9783b0d85 100644 --- a/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$externRef.md +++ b/packages/website/versioned_docs/version-latest/emitters/protobuf/reference/js-api/functions/$externRef.md @@ -5,7 +5,7 @@ title: "[F] $externRef" --- ```ts function $externRef( - ctx, + context, target, path, name): void @@ -15,10 +15,10 @@ function $externRef( | Parameter | Type | | ------ | ------ | -| `ctx` | `DecoratorContext` | +| `context` | `DecoratorContext` | | `target` | `Model` | -| `path` | `StringLiteral` | -| `name` | `StringLiteral` | +| `path` | `Type` | +| `name` | `Type` | ## Returns diff --git a/packages/website/versioned_docs/version-latest/extending-typespec/create-decorators.md b/packages/website/versioned_docs/version-latest/extending-typespec/create-decorators.md index 199d21820..3c4986ea2 100644 --- a/packages/website/versioned_docs/version-latest/extending-typespec/create-decorators.md +++ b/packages/website/versioned_docs/version-latest/extending-typespec/create-decorators.md @@ -71,7 +71,21 @@ const tagName: string = "widgets"; ## JavaScript decorator implementation -Decorators can be implemented in JavaScript by prefixing the function name with `$`. A decorator function must have the following parameters: +Decorators can be implemented in JavaScript in 2 ways: + +1. Prefixing the function name with `$`. e.g `export function $doc(target, name) {...}` **Great to get started/play with decorators** +2. Exporting all decorators for your library using `$decorators` variable. **Recommended** + +```ts +export const $decorators = { + // Namespace + "MyOrg.MyLib": { + doc: docDecoratorFn, + }, +}; +``` + +A decorator implementation takes the following parameters: - `1`: `context` of type `DecoratorContext` - `2`: `target` The TypeSpec type target. (`Namespace`, `Interface`, etc.) 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 index e08e16f64..e7ade3d7c 100644 --- 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 @@ -8,23 +8,54 @@ pagination_next: getting-started/getting-started-rest/02-operations-responses # ## 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. +Welcome to 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. + +### What is TypeSpec? + +TypeSpec is a language and toolset developed by Microsoft for defining data models and service APIs. It provides a structured way to describe the shape and behavior of data and services, ensuring consistency and reducing errors in API development. With TypeSpec, you can generate code, documentation, and other artifacts from your API definitions, making it easier to maintain and evolve your services. Microsoft uses TypeSpec internally to define APIs for various products and services, including Azure. + +TypeSpec is used to define the **interface** of your API, which clients will use to interact with resources provided by your service. This includes specifying the operations, request and response models, and error handling mechanisms. The actual API logic is implemented in the backend service, which processes the requests and communicates with the database. 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/). +1. **Install Node.js**: Download and install Node.js from [nodejs.org](https://nodejs.org/). This will also install npm, the Node.js package manager. The minimum versions required are Node.js 20.0.0 and npm 7.0.0. 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. + - Run `tsp compile .` to compile the initial file. + - Run `tsp compile . --watch` to automatically compile changes on save. + +### Project Structure Overview + +Once you've completed these steps, you'll have a basic TypeSpec project set up. Here's an overview of the files and directories in your TypeSpec project: + +``` +Project Root +├── main.tsp +├── tspconfig.yaml +├── package.json +├── node_modules/ +└── tsp-output/ +``` + +- **main.tsp**: Entry point for TypeSpec definitions. +- **tspconfig.yaml**: TypeSpec compiler configuration. +- **package.json**: Project metadata and dependencies. +- **node_modules/**: Installed dependencies. +- **tsp-output/**: Generated files. +- **openapi.yaml**: Generated OpenAPI specification. + +As we work through the tutorial, keep the openapi.yaml file open in Visual Studio or VS Code to watch the API specification evolve as we make changes. ## 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. +Now that we have our environment set up, let's dive into the basic syntax and structure of TypeSpec. We'll create a simple REST API for a pet store by introducing concepts in a layered fashion, increasing complexity as we progress through the tutorial. + +As the tutorial advances and the code examples grow more complex, we'll highlight changes in the code to help you easily spot where new lines have been added. ### Import and Using Statements @@ -32,11 +63,11 @@ Before defining models and services, we need to import the necessary TypeSpec li 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. +You can also alternatively use the `Try it` feature with the code samples to quickly 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 +```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; using TypeSpec.Http; @@ -47,7 +78,69 @@ 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 +**NOTE: Your generated project file likely already has these import/using statements, plus import/using for the `@typespec/openapi3` library. The `@typespec/openapi3` library is necessary for emitting the OpenAPI specification file but is not required for creating our Pet Store API in TypeSpec. Remove them from your `main.tsp` file so your code matches the example above.** + +## 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: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; +// highlight-start +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +// highlight-end +``` + +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". + +**OpenAPI Comparison**: In OpenAPI, this is similar to defining the `info` object (which includes the title) and the `servers` array (which includes the server URL). + +**NOTE: This code will not compile as-is because we've not yet defined a `namespace` for these decorators to apply to. We'll cover that topic next.** + +## 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: + +```tsp tryit="{"emit": ["@typespec/openapi3"]}" +import "@typespec/http"; + +using TypeSpec.Http; + +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") + +// highlight-next-line +namespace PetStore; +``` + +In this example: + +- The `namespace` keyword is used to define a top-level namespace named `PetStore`. +- All models and operations related to the Pet Store service will be defined within this namespace. +- The first use of namespace defines the top-level namespace and does not require brackets. This is because it serves as the primary container for all related definitions. +- Any subsequent namespaces defined within this top-level namespace will require brackets {} to indicate that they are nested within the top-level namespace. + +**OpenAPI Comparison**: In OpenAPI, namespaces are similar to using tags to group related operations and definitions. + +## Defining 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. @@ -55,11 +148,18 @@ In TypeSpec, a [model](../../language-basics/models.md) is a fundamental buildin Let's define a simple model for a `Pet`: -```typespec +```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; using TypeSpec.Http; +@service({ + title: "Pet Store", +}) +@server("https://example.com", "Single server endpoint") +namespace PetStore; + +// highlight-start model Pet { id: int32; name: string; @@ -74,6 +174,7 @@ enum petType { bird: "bird", reptile: "reptile", } +// highlight-end ``` In this example: @@ -82,22 +183,33 @@ In this example: - 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. +**OpenAPI Comparison**: In OpenAPI, this is similar to defining a `schema` object under the `components` section, where you define the structure and properties of your data models. + ### Example: Adding Validation Annotations We can add [validation](../../language-basics/values#validation) annotations to our model properties to enforce certain constraints: -```typespec +```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; + // highlight-next-line @minLength(1) name: string; + // highlight-next-line @minValue(0) + // highlight-next-line @maxValue(100) age: int32; @@ -118,219 +230,10 @@ 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. +**OpenAPI Comparison**: In OpenAPI, this is similar to using `minLength`, `minimum`, and `maximum` constraints within the `schema` object. ## 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 this section, we introduced you to TypeSpec, set up the development environment, and covered basic language syntax and structure. We defined a simple REST service, organized our API using namespaces, and defined a model with validation annotations. -In the next section, we'll dive deeper into defining more HTTP operations and handling different types of responses. +With this foundational knowledge, you're now ready to dive deeper into defining operations and handling different types of responses in your REST API. In the next section, we'll expand our API by adding CRUD operations. 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 index 4ad41541d..8a840aa62 100644 --- 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 @@ -7,15 +7,15 @@ title: 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. +In this section, we'll build upon the basics we covered in the previous section. We'll define CRUD operations (Create, Read, Update, Delete) for our Pet Store API and discuss the benefits of using nested namespaces. -## Defining More HTTP Operations +## Defining CRUD 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. +Next, we'll discuss how to define CRUD operations for our API. We'll cover operations for `Creating`, `Reading`, `Updating`, and `Deleting` pets, all within a nested namespace for better organization. -### Example: Defining a POST Operation +### Example: Adding CRUD Operations -Let's define a `POST` operation to create a new pet: +Let's define the CRUD operations for our `Pet` model: ```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; @@ -49,87 +49,19 @@ enum petType { reptile: "reptile", } +// highlight-start @route("/pets") namespace Pets { @get op listPets(): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get op getPet(@path petId: int32): { + @statusCode statusCode: 200; @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 @@ -140,114 +72,73 @@ namespace Pets { @put op updatePet(@path petId: int32, @body pet: Pet): { + @statusCode statusCode: 200; @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; -} +// highlight-end ``` 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. +- The `@route` decorator defines the base path for the `Pets` namespace. +- The `listPets` operation lists all pets. +- The `getPet` operation retrieves a specific pet by its `petId`. +- The `createPet` operation creates a new pet. +- The `updatePet` operation updates an existing pet. +- The `deletePet` operation deletes an existing pet. + +### Benefits of Nested Namespaces + +Using nested namespaces in TypeSpec provides several benefits: + +1. **Organization**: Grouping related operations under a common namespace makes the API easier to manage and understand. +2. **Operation IDs**: The TypeSpec compiler appends the namespace name to the `operationId` in the OpenAPI spec, making it clear which resource each operation is intended to operate on. +3. **Clarity**: It helps in avoiding naming conflicts and provides a clear structure for the API. + +#### Example: Operation ID in OpenAPI Spec + +For the `listPets` operation defined in the `Pets` namespace, the OpenAPI spec will generate an `operationId` like `Pets_listPets`, making it clear that this operation is related to the `Pets` resource. + +### Example: Route URLs for CRUD Operations + +Here's what the route URLs will look like for the CRUD operations defined in the `Pets` namespace: + +- **List Pets**: `GET https://example.com/pets` + - Retrieves a list of all pets. +- **Get Pet by ID**: `GET https://example.com/pets/{petId}` + - Retrieves a specific pet by its `petId`. +- **Create Pet**: `POST https://example.com/pets` + - Creates a new pet. +- **Update Pet by ID**: `PUT https://example.com/pets/{petId}` + - Updates an existing pet by its `petId`. +- **Delete Pet by ID**: `DELETE https://example.com/pets/{petId}` + - Deletes an existing pet by its `petId`. + +### Operation Flowchart + +For clarity, here's a flowchart that depicts the flow of data and operations within the API: + +``` +[Client] --> [API Gateway] --> [listPets Operation] --> [Database] --> [Response: List of Pets] +[Client] --> [API Gateway] --> [getPet Operation] --> [Database] --> [Response: Pet Details] +[Client] --> [API Gateway] --> [createPet Operation] --> [Database] --> [Response: Created Pet] +[Client] --> [API Gateway] --> [updatePet Operation] --> [Database] --> [Response: Updated Pet] +[Client] --> [API Gateway] --> [deletePet Operation] --> [Database] --> [Response: Deletion Confirmation] +``` ## 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. +In a real-world API, different operations might return different types of successful responses. Let's see how we can handle various response scenarios in TypeSpec. -### Example: Handling Validation Errors +### Example: Handling Different Status Codes -Let's define a `ValidationError` model and update our `createPet` operation to handle validation errors. +Let's update our pet operations to return different status codes based on the outcome. ```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; @@ -285,61 +176,215 @@ enum petType { namespace Pets { @get op listPets(): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get op getPet(@path petId: int32): { + @statusCode statusCode: 200; @body pet: Pet; + // highlight-start } | { - @body error: NotFoundError; + @statusCode statusCode: 404; + // highlight-end }; @post op createPet(@body pet: Pet): { @statusCode statusCode: 201; @body newPet: Pet; + // highlight-start } | { - @statusCode statusCode: 400; - @body error: ValidationError; + @statusCode statusCode: 202; + @body acceptedPet: Pet; + // highlight-end }; @put op updatePet(@path petId: int32, @body pet: Pet): { + @statusCode statusCode: 200; @body updatedPet: Pet; + // highlight-start } | { - @body error: NotFoundError; + @statusCode statusCode: 404; + // highlight-end }; @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. +- The pet operations are updated to handle different status codes, depending on the outcome of the operation reported by the backend service. + +**Explanation of the `|` Operator**: + +- The `|` operator is used to define multiple possible responses for an operation. Each response block specifies a different status code and response body. +- In the `createPet` operation for example, the `|` operator allows the operation to return either a 201 status code with a `newPet` object or a 202 status code with an `acceptedPet` object. + +### OpenAPI Spec Mapping + +Here is how the TypeSpec operation definitions map to the OpenAPI specification: + +
+
+

TypeSpec Definition:

+ 

+@route("/pets")
+namespace Pets {
+
+
+@get
+op listPets(): {
+@statusCode statusCode: 200;
+@body pets: Pet[];
+};
+
+@get
+op getPet(@path petId: int32): {
+@statusCode statusCode: 200;
+@body pet: Pet;
+} | {
+@statusCode statusCode: 404;
+};
+
+@post
+op createPet(@body pet: Pet): {
+@statusCode statusCode: 201;
+@body newPet: Pet;
+} | {
+@statusCode statusCode: 202;
+@body acceptedPet: Pet;
+};
+
+@put
+op updatePet(@path petId: int32, @body pet: Pet):{
+@statusCode statusCode: 200;
+@body updatedPet: Pet;
+} | {
+@statusCode statusCode: 404;
+} | {
+@statusCode statusCode: 500;
+};
+
+@delete
+op deletePet(@path petId: int32): {
+@statusCode statusCode: 204;
+@body NoContentResponse;
+} | {
+@statusCode statusCode: 404;
+};
+}
+
+ +
+
+

OpenAPI Spec:

+ 

+paths:
+  /pets:
+    get:
+      operationId: Pets_listPets
+      parameters: []
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Pet'
+    post:
+      operationId: Pets_createPet
+      parameters: []
+      responses:
+        '201':
+          description: The request has succeeded and a new resource has been created as a result.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        '202':
+          description: The request has been accepted for processing, but processing has not yet completed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+  /pets/{petId}:
+    get:
+      operationId: Pets_getPet
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        '404':
+          description: The server cannot find the requested resource.
+    put:
+      operationId: Pets_updatePet
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        '404':
+          description: The server cannot find the requested resource.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+    delete:
+      operationId: Pets_deletePet
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '204':
+          description: 'There is no content to send for this request, but the headers may be useful. '
+
+
+
+ +**Note**: As you can see, TypeSpec is much more compact and easier to read compared to the equivalent OpenAPI specification. ## 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 this section, we demonstrated how to define CRUD operations for your REST API using TypeSpec and discussed the benefits of using nested namespaces. We also covered how to handle different types of successful responses. 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 index c5d4a4c79..7a0e86854 100644 --- 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 @@ -6,7 +6,17 @@ title: Handling Errors ## 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. +In this section, we'll focus on handling errors in your REST API. We'll define error models and demonstrate how to add them as possible responses to your CRUD operations. + +## Why Use Error Models? + +Using error models instead of raw status codes offers several advantages: + +1. **Consistency**: Error models ensure that error responses are consistent across your API. This makes it easier for clients to handle errors predictably. +2. **Clarity**: Error models provide clear, structured information about the error, including error codes, messages, and additional details. This helps developers understand what went wrong and how to fix it. +3. **Extensibility**: Error models can be extended to include additional information, such as error details, validation issues, or links to documentation. This makes it easier to provide comprehensive error information. +4. **Documentation**: Error models improve the generated API documentation by clearly defining the structure of error responses. This helps API consumers understand the possible error responses and how to handle them. +5. **Type Safety**: In strongly-typed languages, using error models can provide type safety, ensuring that error responses conform to the expected structure. ## Defining Error Models @@ -14,7 +24,7 @@ Error models can be used to represent different types of errors that your API mi ### 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: +We'll define models to represent validation errors, not-found errors, and internal server errors: ```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; @@ -52,13 +62,18 @@ enum petType { namespace Pets { @get op listPets(): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get op getPet(@path petId: int32): { + @statusCode statusCode: 200; @body pet: Pet; } | { + @statusCode statusCode: 404; + + // highlight-next-line @body error: NotFoundError; }; @@ -67,240 +82,43 @@ namespace Pets { @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: 202; + @body acceptedPet: Pet; + // highlight-start } | { @statusCode statusCode: 400; @body error: ValidationError; }; + // highlight-end @put op updatePet(@path petId: int32, @body pet: Pet): | { + @statusCode statusCode: 200; @body updatedPet: Pet; - } - | { - @body error: NotFoundError; + // highlight-start } | { @statusCode statusCode: 400; @body error: ValidationError; } - | InternalServerErrorResponse; + | { + @statusCode statusCode: 404; + @body error: NotFoundError; + } + | { + @statusCode statusCode: 500; + @body error: InternalServerError; + // highlight-end + }; @delete op deletePet(@path petId: int32): { @statusCode statusCode: 204; - } | { - @body error: NotFoundError; }; } +// highlight-start @error model NotFoundError { code: "NOT_FOUND"; @@ -319,20 +137,17 @@ model InternalServerError { code: "INTERNAL_SERVER_ERROR"; message: string; } - -model InternalServerErrorResponse { - @statusCode statusCode: 500; - @body error: InternalServerError; -} +// highlight-end ``` 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. +- The `NotFoundError`, `ValidationError`, and `InternalServerError` models are defined to represent different types of errors. +- The `@error` decorator is used to indicate that these models represent error responses. +- The Pet Store operations are updated to return the appropriate error models when the service can't perform the requested operation. ## 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 this section, we focused on defining error handling in your REST API. We introduced error models and demonstrated how to represent different operation response scenarios in TypeSpec. 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 index 0ea342028..066fecef7 100644 --- 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 @@ -10,13 +10,13 @@ In this section, we'll focus on reusing common parameters in your REST API. Comm ## 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. +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`: +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 +```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; using TypeSpec.Http; @@ -26,6 +26,7 @@ using TypeSpec.Http; }) @server("https://example.com", "Single server endpoint") namespace PetStore; + model Pet { id: int32; @@ -47,6 +48,7 @@ enum petType { reptile: "reptile", } +// highlight-start model CommonParameters { @header requestID: string; @@ -57,6 +59,7 @@ model CommonParameters { @header clientVersion?: string; } +// highlight-end ``` In this example: @@ -116,45 +119,59 @@ model CommonParameters { @route("/pets") namespace Pets { @get + // highlight-next-line op listPets(...CommonParameters): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get + // highlight-next-line op getPet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 200; @body pet: Pet; } | { + @statusCode statusCode: 404; @body error: NotFoundError; }; @post + // highlight-next-line op createPet(@body pet: Pet, ...CommonParameters): { @statusCode statusCode: 201; @body newPet: Pet; + } | { + @statusCode statusCode: 202; + @body acceptedPet: Pet; } | { @statusCode statusCode: 400; @body error: ValidationError; }; @put + // highlight-next-line op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): | { + @statusCode statusCode: 200; @body updatedPet: Pet; } - | { - @body error: NotFoundError; - } | { @statusCode statusCode: 400; @body error: ValidationError; } - | InternalServerErrorResponse; + | { + @statusCode statusCode: 404; + @body error: NotFoundError; + } + | { + @statusCode statusCode: 500; + @body error: InternalServerError; + }; @delete + // highlight-next-line op deletePet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 204; - } | { - @body error: NotFoundError; }; } @@ -176,11 +193,6 @@ model InternalServerError { code: "INTERNAL_SERVER_ERROR"; message: string; } - -model InternalServerErrorResponse { - @statusCode statusCode: 500; - @body error: InternalServerError; -} ``` In this example: @@ -188,8 +200,84 @@ 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. +### Example: OpenAPI Specification for Common Parameters + +Let's take a closer look at how the common parameters model with the `spread` operator is represented in the generated OpenAPI specification by looking at the `deletePet` operation: + +```yaml +#### Generated OpenAPI Specification: + +paths: + /pets/{petId}: + delete: + operationId: Pets_deletePet + parameters: + - name: petId + in: path + required: true + schema: + type: integer + format: int32 + // highlight-start + - $ref: "#/components/parameters/CommonParameters.requestID" + - $ref: "#/components/parameters/CommonParameters.locale" + - $ref: "#/components/parameters/CommonParameters.clientVersion" + // highlight-end + responses: + "204": + description: "There is no content to send for this request, but the headers may be useful." + "404": + description: "Not Found" + content: + application/json: + schema: + $ref: "#/components/schemas/NotFoundError" +components: + parameters: + // highlight-start + CommonParameters.clientVersion: + name: client-version + in: header + required: false + schema: + type: string + CommonParameters.locale: + name: locale + in: query + required: false + schema: + type: string + CommonParameters.requestID: + name: request-id + in: header + required: true + schema: + type: string + // highlight-end + schemas: + NotFoundError: + type: object + properties: + code: + type: string + example: "NOT_FOUND" + message: + type: string +``` + +In this example: + +- **Parameters Section**: The `deletePet` operation includes the `petId` path parameter and the common parameters (`requestID`, `locale`, and `clientVersion`). The common parameters are referenced using `$ref` to ensure they are consistently defined and reused across multiple operations. +- **Components Section**: The common parameters are defined under the `components` section, ensuring they are reusable and maintainable. Each parameter is specified with its name, location (`in` indicating header or query), whether it is required, and its schema. + +### Benefits + +1. **Consistency**: Ensures that common parameters are applied consistently across all relevant operations. +2. **Maintainability**: Changes to common parameters need to be made only once in the `CommonParameters` model, reducing redundancy and potential errors. +3. **Clarity**: The generated OpenAPI specification clearly shows which parameters are required for each operation, improving the documentation and usability of the API. + ## 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 this section, we focused on reusing common parameters in your REST API. 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. +Next, we'll learn how to add authentication to our 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 index b2f4ccb8c..4365b93e7 100644 --- 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 @@ -6,15 +6,17 @@ title: Authentication ## 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. +In this section, we'll focus on adding [authentication](../../libraries/http/authentication) to your REST API. We'll introduce the `@useAuth` decorator, show how to enforce 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. +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. The server validates the token to grant access to the resource. + ### 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. +Let's update our existing operations to enforce authentication using the `@useAuth` decorator. We'll add authentication to the operations that modify pet data: creating, updating, and deleting pets. We'll also add a new error model for unauthorized access. ```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; @@ -63,47 +65,80 @@ model CommonParameters { namespace Pets { @get op listPets(...CommonParameters): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get op getPet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 200; @body pet: Pet; } | { + @statusCode statusCode: 404; @body error: NotFoundError; }; @post + // highlight-next-line @useAuth(BearerAuth) - op createPet(@body pet: Pet, ...CommonParameters): { - @statusCode statusCode: 201; - @body newPet: Pet; - } | { - @statusCode statusCode: 400; - @body error: ValidationError; - }; + op createPet(@body pet: Pet, ...CommonParameters): + | { + @statusCode statusCode: 201; + @body newPet: Pet; + } + | { + @statusCode statusCode: 202; + @body acceptedPet: Pet; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + // highlight-start + } + | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; + // highlight-end + }; @put + // highlight-next-line @useAuth(BearerAuth) op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): | { + @statusCode statusCode: 200; @body updatedPet: Pet; } - | { - @body error: NotFoundError; - } | { @statusCode statusCode: 400; @body error: ValidationError; } - | InternalServerErrorResponse; + | { + // highlight-start + @statusCode statusCode: 401; + + @body error: UnauthorizedError; + // highlight-end + } + | { + @statusCode statusCode: 404; + @body error: NotFoundError; + } + | { + @statusCode statusCode: 500; + @body error: InternalServerError; + }; @delete + // highlight-next-line @useAuth(BearerAuth) op deletePet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 204; + // highlight-start } | { - @body error: NotFoundError; + @statusCode statusCode: 401; + @body error: UnauthorizedError; + // highlight-end }; } @@ -120,6 +155,14 @@ model ValidationError { details: string[]; } +// highlight-start +@error +model UnauthorizedError { + code: "UNAUTHORIZED"; + message: string; +} +// highlight-end + @error model InternalServerError { code: "INTERNAL_SERVER_ERROR"; @@ -135,8 +178,91 @@ model InternalServerErrorResponse { 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. +- A new error model, `UnauthorizedError`, is defined to handle unauthorized access errors. +- The `UnauthorizedError` model is used in the `createPet`, `updatePet`, and `deletePet` operations to indicate unauthorized access. + +### Example: OpenAPI Specification with Authentication + +Let's take a closer look at how the `@useAuth` decorator affects the generated OpenAPI specification for the `deletePet` operation. + +```yaml +paths: + /pets/{petId}: + delete: + operationId: Pets_deletePet + parameters: + - name: petId + in: path + required: true + schema: + type: integer + format: int32 + - $ref: "#/components/parameters/CommonParameters.requestID" + - $ref: "#/components/parameters/CommonParameters.locale" + - $ref: "#/components/parameters/CommonParameters.clientVersion" + // highlight-start + security: + - BearerAuth: [] + // highlight-end + responses: + "204": + description: "There is no content to send for this request, but the headers may be useful." + "404": + description: "Not Found" + content: + application/json: + schema: + $ref: "#/components/schemas/NotFoundError" +components: + parameters: + CommonParameters.clientVersion: + name: client-version + in: header + required: false + schema: + type: string + CommonParameters.locale: + name: locale + in: query + required: false + schema: + type: string + CommonParameters.requestID: + name: request-id + in: header + required: true + schema: + type: string + // highlight-start + securitySchemes: + BearerAuth: + type: http + scheme: bearer + // highlight-end + schemas: + NotFoundError: + type: object + properties: + code: + type: string + example: "NOT_FOUND" + message: + type: string +``` + +### Explanation + +- **Security Section**: The `security` section in the `deletePet` operation specifies that Bearer authentication is required. This is indicated by the `BearerAuth` security scheme. +- **Security Schemes**: The `components` section includes a `securitySchemes` definition for `BearerAuth`, specifying that it uses the HTTP bearer authentication scheme. + +### Benefits + +1. **Security**: Ensures that only authorized clients can perform certain actions by enforcing authentication on specific operations. +2. **Consistency**: The use of common parameters and authentication mechanisms is consistently applied across relevant operations. +3. **Clarity**: The generated OpenAPI specification clearly shows which operations require authentication and which parameters are needed, improving the documentation and usability of the API. ## 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. + +In the next section, we'll dive into versioning your REST API. Versioning allows you to introduce new features and improvements while maintaining backward compatibility for existing clients. 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 index 450152371..d0fcf4873 100644 --- 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 @@ -14,17 +14,25 @@ Before we can use the versioning decorators, we need to add the `@typespec/versi ### Step 1: Update `package.json` -Add the `@typespec/versioning` library to your `package.json` file: +Add the `@typespec/versioning` library to your `package.json` file, in both the `peerDependencies` and `devDependencies` sections. Your updated `package.json` should look like this: ```json { - "name": "tsp_pet_store", + "name": "typespec-petstore", "version": "0.1.0", "type": "module", - "dependencies": { + "peerDependencies": { "@typespec/compiler": "latest", "@typespec/http": "latest", "@typespec/openapi3": "latest", + // highlight-next-line + "@typespec/versioning": "latest" + }, + "devDependencies": { + "@typespec/compiler": "latest", + "@typespec/http": "latest", + "@typespec/openapi3": "latest", + // highlight-next-line "@typespec/versioning": "latest" }, "private": true @@ -47,24 +55,29 @@ The [`@versioned`](../../libraries/versioning/reference/decorators#@TypeSpec.Ver Let's define two versions of our API, `v1` and `v2`: -```typespec +```tsp tryit="{"emit": ["@typespec/openapi3"]}" import "@typespec/http"; +// highlight-next-line import "@typespec/versioning"; using TypeSpec.Http; +// highlight-next-line using TypeSpec.Versioning; @service({ title: "Pet Store", }) @server("https://example.com", "Single server endpoint") +// highlight-next-line @versioned(Versions) namespace PetStore; +// highlight-start enum Versions { v1: "1.0", v2: "2.0", } +// highlight-end ``` In this example: @@ -73,6 +86,28 @@ In this example: - 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). +### 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: + +```tsp +main.tsp +tspconfig.yaml +package.json +node_modules/ +tsp-output/ +┗ @typespec/ + ┗ openapi3/ + // highlight-start + ┣ openapi.1.0.yaml + ┗ openapi.2.0.yaml + // highlight-end +``` + +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. + +By encapsulating different versions of the API within the context of the same TypeSpec project, we can manage all versions in a unified manner. This approach makes it easier to maintain consistency, apply updates, and ensure that all versions are properly documented and aligned with the overall API strategy. + ## 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. @@ -121,11 +156,13 @@ enum petType { reptile: "reptile", } +// highlight-start @added(Versions.v2) model Toy { id: int32; name: string; } +// highlight-end ``` In this example: @@ -199,55 +236,83 @@ model CommonParameters { namespace Pets { @get op listPets(...CommonParameters): { + @statusCode statusCode: 200; @body pets: Pet[]; }; @get op getPet(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 200; @body pet: Pet; } | { + @statusCode statusCode: 404; @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): + op createPet(@body pet: Pet, ...CommonParameters): | { - @body updatedPet: Pet; + @statusCode statusCode: 201; + @body newPet: Pet; } | { - @body error: NotFoundError; + @statusCode statusCode: 202; + @body acceptedPet: Pet; } | { @statusCode statusCode: 400; @body error: ValidationError; } - | InternalServerErrorResponse; + | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; + }; + + @put + @useAuth(BearerAuth) + op updatePet(@path petId: int32, @body pet: Pet, ...CommonParameters): + | { + @statusCode statusCode: 200; + @body updatedPet: Pet; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; + } + | { + @statusCode statusCode: 404; + @body error: NotFoundError; + } + | { + @statusCode statusCode: 500; + @body error: InternalServerError; + }; @delete @useAuth(BearerAuth) op deletePet(@path petId: int32, ...CommonParameters): { @statusCode statusCode: 204; } | { - @body error: NotFoundError; + @statusCode statusCode: 401; + @body error: UnauthorizedError; }; + // highlight-start @route("{petId}/toys") namespace Toys { @added(Versions.v2) @get op listToys(@path petId: int32, ...CommonParameters): { + @statusCode statusCode: 200; @body toys: Toy[]; + } | { + @statusCode statusCode: 404; + @body error: NotFoundError; }; @added(Versions.v2) @@ -256,22 +321,45 @@ namespace Pets { op createToy(@path petId: int32, @body toy: Toy, ...CommonParameters): { @statusCode statusCode: 201; @body newToy: Toy; + } | { + @statusCode statusCode: 400; + @body error: ValidationError; + } | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; }; @added(Versions.v2) @put @useAuth(BearerAuth) - op updateToy(@path petId: int32, @path toyId: int32, @body toy: Toy, ...CommonParameters): { - @body updatedToy: Toy; - }; + op updateToy(@path petId: int32, @path toyId: int32, @body toy: Toy, ...CommonParameters): + | { + @body updatedToy: Toy; + } + | { + @statusCode statusCode: 400; + @body error: ValidationError; + } + | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; + } + | { + @statusCode statusCode: 404; + @body error: NotFoundError; + }; @added(Versions.v2) @delete @useAuth(BearerAuth) op deleteToy(@path petId: int32, @path toyId: int32, ...CommonParameters): { @statusCode statusCode: 204; + } | { + @statusCode statusCode: 401; + @body error: UnauthorizedError; }; } + // highlight-end } @error @@ -287,6 +375,12 @@ model ValidationError { details: string[]; } +@error +model UnauthorizedError { + code: "UNAUTHORIZED"; + message: string; +} + @error model InternalServerError { code: "INTERNAL_SERVER_ERROR"; @@ -305,26 +399,6 @@ In this example: - 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. +In the next section, we'll dive into creating custom response models for your REST API. 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 index 2fddaa65e..ecd507114 100644 --- 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 @@ -6,31 +6,39 @@ title: 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. +In this section, we'll focus on creating custom response models and demonstrate how to use them in your API operations. We'll also incorporate predefined 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. +### Common HTTP Status Codes and TypeSpec Response Models + +Here are some common HTTP status codes and their equivalent TypeSpec response models from the TypeSpec HTTP library: + +| **HTTP Status Code** | **Meaning** | **TypeSpec Response Model** | +| -------------------- | --------------------------------------------------------------------------- | --------------------------- | +| 200 OK | The request was successful, and the server returned the requested resource. | `OkResponse` | +| 201 Created | The request was successful, and a new resource was created. | `CreatedResponse` | +| 204 No Content | The request was successful, but there is no content to return. | `NoContentResponse` | +| 400 Bad Request | The server could not understand the request due to invalid syntax. | `BadRequestResponse` | +| 401 Unauthorized | The client must authenticate itself to get the requested response. | `UnauthorizedResponse` | +| 403 Forbidden | The client does not have access rights to the content. | `ForbiddenResponse` | +| 404 Not Found | The server cannot find the requested resource. | `NotFoundResponse` | + ### 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 +## Creating Custom Response Models -Let's start by defining some basic custom response models. We'll incorporate existing response models from the TypeSpec HTTP library. +Let's start by defining and extending some custom response models. These models will incorporate existing response models from the TypeSpec HTTP library to ensure consistency. -### Example: Defining Basic Custom Response Models - -```typespec -import "@typespec/http"; -import "@typespec/versioning"; - -using TypeSpec.Http; -using TypeSpec.Versioning; +### Example: Defining and Extending Custom Response Models +```tsp model PetListResponse { ...OkResponse; ...Body; @@ -50,6 +58,25 @@ model PetErrorResponse { ...BadRequestResponse; ...Body; } + +model PetNotFoundResponse { + ...NotFoundResponse; + ...Body; +} + +model PetUnauthorizedResponse { + ...UnauthorizedResponse; + ...Body; +} + +model PetSuccessResponse { + ...OkResponse; + ...Body; +} + +model PetNoContentResponse { + ...NoContentResponse; +} ``` In this example: @@ -58,35 +85,12 @@ In this example: - `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. +- `PetUnauthorizedResponse` extends `UnauthorizedResponse` and includes a body with an `UnauthorizedError` object. - `PetSuccessResponse` extends `OkResponse` and includes a body with a success message. +- `PetNoContentResponse` extends `NoContentResponse` for situations where the request succeeded but there is no content to return. + +**Note**: Base response models like `OkResponse`, `CreatedResponse`, `BadRequestResponse`, `NotFoundResponse`, and `UnauthorizedResponse` are imported from the TypeSpec [HTTP data types library](../../libraries/http/reference/data-types), which we're importing in our project as `@typespec/http`. ## Using Custom Response Models in Operations @@ -151,6 +155,7 @@ model CommonParameters { clientVersion?: string; } +// highlight-start model PetListResponse { ...OkResponse; ...Body; @@ -166,6 +171,11 @@ model PetCreatedResponse { ...Body; } +model PetAcceptedResponse { + ...AcceptedResponse; + ...Body; +} + model PetErrorResponse { ...BadRequestResponse; ...Body; @@ -178,7 +188,7 @@ model PetNotFoundResponse { model PetUnauthorizedResponse { ...UnauthorizedResponse; - ...Body; + ...Body; } model PetSuccessResponse { @@ -186,34 +196,47 @@ model PetSuccessResponse { ...Body; } +model PetNoContentResponse { + ...NoContentResponse; +} +// highlight-end + @route("/pets") namespace Pets { @get - op listPets(...CommonParameters): PetListResponse | BadRequestResponse; + // highlight-next-line + op listPets(...CommonParameters): PetListResponse; @get - op getPet( - @path petId: int32, - @header ifMatch?: string, - ): PetResponse | PetNotFoundResponse | BadRequestResponse; - + // highlight-start + op getPet(@path petId: int32, @header ifMatch?: string): PetResponse | PetNotFoundResponse; + // highlight-end @useAuth(BearerAuth) @post - op createPet(@body pet: Pet): PetCreatedResponse | PetErrorResponse; + // highlight-start + op createPet(@body pet: Pet): + | PetCreatedResponse + | PetAcceptedResponse + | PetErrorResponse + | PetUnauthorizedResponse; + // highlight-end @useAuth(BearerAuth) @put + // highlight-start op updatePet(@path petId: int32, @body pet: Pet): | PetResponse - | PetNotFoundResponse + | PetErrorResponse | PetUnauthorizedResponse + | PetNotFoundResponse | InternalServerErrorResponse; + // highlight-end @useAuth(BearerAuth) @delete - op deletePet( - @path petId: int32, - ): PetNotFoundResponse | PetSuccessResponse | PetUnauthorizedResponse; + // highlight-start + op deletePet(@path petId: int32): PetNoContentResponse | PetUnauthorizedResponse; + // highlight-end @route("{petId}/toys") namespace Toys { @@ -260,6 +283,12 @@ model ValidationError { details: string[]; } +@error +model UnauthorizedError { + code: "UNAUTHORIZED"; + message: string; +} + @error model InternalServerError { code: "INTERNAL_SERVER_ERROR"; @@ -275,13 +304,13 @@ model InternalServerErrorResponse { 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. +- The `getPet` operation uses the `PetResponse` and `PetNotFoundResponse` custom response models. +- The `createPet` operation uses the `PetCreatedResponse`, `PetAcceptedResponse`, `PetErrorResponse`, and `PetUnauthorizedResponse` custom response models. +- The `updatePet` operation uses the `PetResponse`, `PetErrorResponse`, `PetUnauthorizedResponse`, `PetNotFoundResponse`, and `InternalServerErrorResponse` custom response models. +- The `deletePet` operation uses the `PetNoContentResponse` 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. +In this section, we focused on creating custom response models in your REST API. By defining and extending 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 index 163081d73..4d0071cd4 100644 --- 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 @@ -12,7 +12,7 @@ Throughout this tutorial, we've covered a wide range of topics to help you build - **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. +- **Handling Errors**: We created error 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. @@ -28,6 +28,6 @@ To continue learning and exploring TypeSpec, here are some additional resources: ## 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. +We value your feedback and would love to hear about your experiences with this tutorial. Please feel free to share your thoughts and suggestions in our [GitHub discussions channel](https://github.com/microsoft/typespec/discussions). -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. +Join the TypeSpec community on [Discord](https://aka.ms/typespec/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/handbook/formatter.md b/packages/website/versioned_docs/version-latest/handbook/formatter.md index bae7a0e35..a4363449a 100644 --- a/packages/website/versioned_docs/version-latest/handbook/formatter.md +++ b/packages/website/versioned_docs/version-latest/handbook/formatter.md @@ -31,6 +31,39 @@ When you use the extensions for VS Code or Visual Studio, the tsp formatter beco If you're working within a TypeSpec file, you can format the document using the default keyboard shortcut for formatting, `alt+shift+F`. +### Configuration - Prettier + +If a prettier config (`.prettierrc.yaml`, `.prettierrc.json`, etc.) is present in the project, the formatter will use the configuration from there. +By default this will then use the typespec style guide without any explicit option. + +:::note +This only affect the formatting, when using `tab` key to indent it will still use the editor's configuration, so recommend setting one of the configuration below. +::: + +### Configuration - VSCode + +For VSCode to respect the TypeSpec standard style set the following options style + +```json +{ + ["typespec"]: { + "editor.detectIndentation": false, + "editor.insertSpaces": true, + "editor.tabSize": 2, + } +} +``` + +### Configuration - EditorConfig + +If using `.editorconfig` with the editor config extension + +```editorconfig +[*.tsp] +indent_size = 2 +indent_style = space +``` + ## Via prettier The tsp formatter is essentially a `prettier` plugin. If you already have a `prettier` configuration set up for other languages, it can be quite handy to simply integrate TypeSpec into this existing pipeline. diff --git a/packages/website/versioned_docs/version-latest/introduction/installation.md b/packages/website/versioned_docs/version-latest/introduction/installation.md index af6653557..e219918c2 100644 --- a/packages/website/versioned_docs/version-latest/introduction/installation.md +++ b/packages/website/versioned_docs/version-latest/introduction/installation.md @@ -39,7 +39,7 @@ Run the following command in a clean directory to create a new TypeSpec project. tsp init ``` -This will prompt you with a few questions. Pick the `Generic REST API` template, your project name, and select the `@typespec/openapi3` library. +This will prompt you with a few questions. Pick the `Generic REST API` template, your project name, and make sure the `@typespec\http` and `@typespec/openapi3` libraries are selected. Next, you can install the dependencies. @@ -47,6 +47,12 @@ Next, you can install the dependencies. tsp install ``` +Run a build to generate the OpenAPI specification output file. + +```bash +tsp compile . +``` + You should now have a basic TypeSpec project setup with a structure looking like this: ```bash @@ -67,10 +73,4 @@ tsp-output/ - **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/reference/js-api/functions/$onValidate.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$onValidate.md deleted file mode 100644 index 42cb14e22..000000000 --- a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/$onValidate.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -jsApi: true -title: "[F] $onValidate" - ---- -```ts -function $onValidate(program): void -``` - -## Parameters - -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | - -## Returns - -`void` diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/addQueryParamsToUriTemplate.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/addQueryParamsToUriTemplate.md new file mode 100644 index 000000000..2ab30c8d1 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/addQueryParamsToUriTemplate.md @@ -0,0 +1,19 @@ +--- +jsApi: true +title: "[F] addQueryParamsToUriTemplate" + +--- +```ts +function addQueryParamsToUriTemplate(uriTemplate, params): string +``` + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `uriTemplate` | `string` | +| `params` | [`HttpOperationParameter`](../type-aliases/HttpOperationParameter.md)[] | + +## Returns + +`string` diff --git a/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getUriTemplatePathParam.md b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getUriTemplatePathParam.md new file mode 100644 index 000000000..e2c9be175 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/http/reference/js-api/functions/getUriTemplatePathParam.md @@ -0,0 +1,18 @@ +--- +jsApi: true +title: "[F] getUriTemplatePathParam" + +--- +```ts +function getUriTemplatePathParam(param): string +``` + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `param` | [`HttpOperationPathParameter`](../type-aliases/HttpOperationPathParameter.md) | + +## Returns + +`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 1b674a47e..d096fa1aa 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 @@ -94,7 +94,6 @@ title: "[P] JS API" - [$header](functions/$header.md) - [$includeInapplicableMetadataInPayload](functions/$includeInapplicableMetadataInPayload.md) - [$multipartBody](functions/$multipartBody.md) -- [$onValidate](functions/$onValidate.md) - [$patch](functions/$patch.md) - [$path](functions/$path.md) - [$post](functions/$post.md) @@ -106,6 +105,7 @@ title: "[P] JS API" - [$statusCode](functions/$statusCode.md) - [$useAuth](functions/$useAuth.md) - [DefaultRouteProducer](functions/DefaultRouteProducer.md) +- [addQueryParamsToUriTemplate](functions/addQueryParamsToUriTemplate.md) - [createMetadataInfo](functions/createMetadataInfo.md) - [getAllHttpServices](functions/getAllHttpServices.md) - [getAllRoutes](functions/getAllRoutes.md) @@ -133,6 +133,7 @@ title: "[P] JS API" - [getStatusCodeDescription](functions/getStatusCodeDescription.md) - [getStatusCodes](functions/getStatusCodes.md) - [getStatusCodesWithDiagnostics](functions/getStatusCodesWithDiagnostics.md) +- [getUriTemplatePathParam](functions/getUriTemplatePathParam.md) - [getVisibilitySuffix](functions/getVisibilitySuffix.md) - [includeInapplicableMetadataInPayload](functions/includeInapplicableMetadataInPayload.md) - [includeInterfaceRoutesInNamespace](functions/includeInterfaceRoutesInNamespace.md) diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/checkDuplicateTypeName.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/checkDuplicateTypeName.md index 2615530c4..e441bd606 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/checkDuplicateTypeName.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/checkDuplicateTypeName.md @@ -11,14 +11,16 @@ function checkDuplicateTypeName( existing): void ``` +Check the given name is not already specific in the existing map. Report a diagnostic if it is. + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `type` | `Type` | -| `name` | `string` | -| `existing` | `undefined` \| `Record`<`string`, `unknown`\> | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `type` | `Type` | Type with the name to check | +| `name` | `string` | Name to check | +| `existing` | `undefined` \| `Record`<`string`, `unknown`\> | Existing map of name | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExtensions.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExtensions.md index ead59bddf..11e1045bc 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExtensions.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExtensions.md @@ -7,12 +7,14 @@ title: "[F] getExtensions" function getExtensions(program, entity): ReadonlyMap ``` +Get extensions set for the given type. + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `entity` | `Type` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `entity` | `Type` | Type | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExternalDocs.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExternalDocs.md index ad354e96a..2c716e41c 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExternalDocs.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getExternalDocs.md @@ -7,12 +7,14 @@ title: "[F] getExternalDocs" function getExternalDocs(program, entity): ExternalDocs | undefined ``` +Return external doc info set via the `@externalDocs` decorator. + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `entity` | `Type` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `entity` | `Type` | Type | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getInfo.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getInfo.md index e03199aef..f368ba906 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getInfo.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getInfo.md @@ -7,12 +7,14 @@ title: "[F] getInfo" function getInfo(program, entity): AdditionalInfo | undefined ``` +Get the info entry for the given service namespace. + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `entity` | `Namespace` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `entity` | `Namespace` | Service namespace | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getOperationId.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getOperationId.md index 0c38e3c4c..c4570de26 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getOperationId.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/getOperationId.md @@ -7,6 +7,8 @@ title: "[F] getOperationId" function getOperationId(program, entity): string | undefined ``` +Returns operationId set via the `@operationId` decorator or `undefined` + ## Parameters | Parameter | Type | @@ -17,9 +19,3 @@ function getOperationId(program, entity): string | undefined ## Returns `string` \| `undefined` - -operationId set via the - -## Operation Id - -decorator or `undefined` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/resolveOperationId.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/resolveOperationId.md index 1db2dec7d..4652060d3 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/resolveOperationId.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/resolveOperationId.md @@ -8,7 +8,9 @@ function resolveOperationId(program, operation): string ``` Resolve the OpenAPI operation ID for the given operation using the following logic: -- If +- If `@operationId` was specified use that value +- If operation is defined at the root or under the service namespace return `` +- Otherwise(operation is under another namespace or interface) return `_` ## Parameters @@ -22,9 +24,3 @@ Resolve the OpenAPI operation ID for the given operation using the following log `string` Operation ID in this format `` or `_` - -## Operation Id - -was specified use that value -- If operation is defined at the root or under the service namespace return `` -- Otherwise(operation is under another namespace or interface) return `_` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setExtension.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setExtension.md index d768a8979..fdac2bda9 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setExtension.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setExtension.md @@ -11,14 +11,16 @@ function setExtension( data): void ``` +Set OpenAPI extension on the given type. Equivalent of using `@extension` decorator + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `entity` | `Type` | -| `extensionName` | \`x-$\{string\}\` | -| `data` | `unknown` | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `entity` | `Type` | Type to annotate | +| `extensionName` | \`x-$\{string\}\` | Extension key | +| `data` | `unknown` | Extension value | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setInfo.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setInfo.md index 6c1636e17..0abda424b 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setInfo.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/functions/setInfo.md @@ -10,13 +10,15 @@ function setInfo( data): void ``` +Set the OpenAPI info node on for the given service namespace. + ## Parameters -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | -| `entity` | `Namespace` | -| `data` | [`AdditionalInfo`](../interfaces/AdditionalInfo.md) & `Record`<\`x-$\{string\}\`, `unknown`\> | +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `program` | `Program` | Program | +| `entity` | `Namespace` | Service namespace | +| `data` | [`AdditionalInfo`](../interfaces/AdditionalInfo.md) & `Record`<\`x-$\{string\}\`, `unknown`\> | OpenAPI Info object | ## Returns diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/index.md index 380f7a2a2..fbd609660 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/index.md @@ -12,11 +12,11 @@ title: "[P] JS API" ## Type Aliases +- [DefaultResponseDecorator](type-aliases/DefaultResponseDecorator.md) +- [ExtensionDecorator](type-aliases/ExtensionDecorator.md) - [ExtensionKey](type-aliases/ExtensionKey.md) - -## Variables - -- [namespace](variables/namespace.md) +- [ExternalDocsDecorator](type-aliases/ExternalDocsDecorator.md) +- [InfoDecorator](type-aliases/InfoDecorator.md) ## Functions diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/Contact.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/Contact.md index 9c8f10da1..470cf5c14 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/Contact.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/Contact.md @@ -3,6 +3,8 @@ jsApi: true title: "[I] Contact" --- +Contact information + ## Properties | Property | Type | Description | diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/ExternalDocs.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/ExternalDocs.md index dd5ad4d97..b5b9da0bf 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/ExternalDocs.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/ExternalDocs.md @@ -3,9 +3,11 @@ jsApi: true title: "[I] ExternalDocs" --- +External Docs info + ## Properties -| Property | Type | -| ------ | ------ | -| `description?` | `string` | -| `url` | `string` | +| Property | Type | Description | +| ------ | ------ | ------ | +| `description?` | `string` | Optional description | +| `url` | `string` | Documentation url | diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/License.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/License.md index 3c006f8fb..832f1b800 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/License.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/interfaces/License.md @@ -3,6 +3,8 @@ jsApi: true title: "[I] License" --- +License information + ## Properties | Property | Type | Description | diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/DefaultResponseDecorator.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/DefaultResponseDecorator.md new file mode 100644 index 000000000..de8cde9c7 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/DefaultResponseDecorator.md @@ -0,0 +1,31 @@ +--- +jsApi: true +title: "[T] DefaultResponseDecorator" + +--- +```ts +type DefaultResponseDecorator: (context, target) => void; +``` + +Specify that this model is to be treated as the OpenAPI `default` response. +This differs from the compiler built-in `@error` decorator as this does not necessarily represent an error. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `context` | `DecoratorContext` | +| `target` | `Model` | + +## Returns + +`void` + +## Example + +```typespec +@defaultResponse +model PetStoreResponse is object; + +op listPets(): Pet[] | PetStoreResponse; +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionDecorator.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionDecorator.md new file mode 100644 index 000000000..c67fec4fd --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionDecorator.md @@ -0,0 +1,31 @@ +--- +jsApi: true +title: "[T] ExtensionDecorator" + +--- +```ts +type ExtensionDecorator: (context, target, key, value) => void; +``` + +Attach some custom data to the OpenAPI element generated from this type. + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `context` | `DecoratorContext` | - | +| `target` | `Type` | - | +| `key` | `string` | Extension key. Must start with `x-` | +| `value` | `Type` | Extension value. | + +## Returns + +`void` + +## Example + +```typespec +@extension("x-custom", "My value") +@extension("x-pageable", {nextLink: "x-next-link"}) +op read(): string; +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionKey.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionKey.md index 7f133f3b1..f3f57cd5c 100644 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionKey.md +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExtensionKey.md @@ -6,3 +6,6 @@ title: "[T] ExtensionKey" ```ts type ExtensionKey: `x-${string}`; ``` + +Pattern for extension keys. +In OpenAPI only unknown properties starting with `x-` are allowed. diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExternalDocsDecorator.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExternalDocsDecorator.md new file mode 100644 index 000000000..e572ffadf --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/ExternalDocsDecorator.md @@ -0,0 +1,30 @@ +--- +jsApi: true +title: "[T] ExternalDocsDecorator" + +--- +```ts +type ExternalDocsDecorator: (context, target, url, description?) => void; +``` + +Specify the OpenAPI `externalDocs` property for this type. + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `context` | `DecoratorContext` | - | +| `target` | `Type` | - | +| `url` | `string` | Url to the docs | +| `description`? | `string` | Description of the docs | + +## Returns + +`void` + +## Example + +```typespec +@externalDocs("https://example.com/detailed.md", "Detailed information on how to use this operation") +op listPets(): Pet[]; +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/InfoDecorator.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/InfoDecorator.md new file mode 100644 index 000000000..b81ee291c --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/type-aliases/InfoDecorator.md @@ -0,0 +1,23 @@ +--- +jsApi: true +title: "[T] InfoDecorator" + +--- +```ts +type InfoDecorator: (context, target, additionalInfo) => void; +``` + +Specify OpenAPI additional information. +The service `title` and `version` are already specified using `@service`. + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `context` | `DecoratorContext` | - | +| `target` | `Namespace` | - | +| `additionalInfo` | `Type` | Additional information | + +## Returns + +`void` diff --git a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/variables/namespace.md b/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/variables/namespace.md deleted file mode 100644 index b13059d83..000000000 --- a/packages/website/versioned_docs/version-latest/libraries/openapi/reference/js-api/variables/namespace.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -jsApi: true -title: "[V] namespace" - ---- -```ts -const namespace: "TypeSpec.OpenAPI" = "TypeSpec.OpenAPI"; -``` diff --git a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/functions/$onValidate.md b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/functions/$onValidate.md deleted file mode 100644 index 42cb14e22..000000000 --- a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/functions/$onValidate.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -jsApi: true -title: "[F] $onValidate" - ---- -```ts -function $onValidate(program): void -``` - -## Parameters - -| Parameter | Type | -| ------ | ------ | -| `program` | `Program` | - -## Returns - -`void` diff --git a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/index.md index 505914cad..2592ae16f 100644 --- a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/index.md @@ -17,7 +17,7 @@ title: "[P] JS API" ## Variables -- [namespace](variables/namespace.md) +- [$lib](variables/$lib.md) ## Functions @@ -32,7 +32,6 @@ title: "[P] JS API" - [$createsResource](functions/$createsResource.md) - [$deletesResource](functions/$deletesResource.md) - [$listsResource](functions/$listsResource.md) -- [$onValidate](functions/$onValidate.md) - [$parentResource](functions/$parentResource.md) - [$readsResource](functions/$readsResource.md) - [$resource](functions/$resource.md) diff --git a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/$lib.md new file mode 100644 index 000000000..51d0af6b7 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/$lib.md @@ -0,0 +1,27 @@ +--- +jsApi: true +title: "[V] $lib" + +--- +```ts +const $lib: TypeSpecLibrary, never>; +``` + +## Type declaration + +| Name | Type | Default value | +| ------ | ------ | ------ | +| `duplicate-key` | `object` | - | +| `duplicate-key.default` | `CallableMessage`<[`"resourceName"`]\> | - | +| `duplicate-parent-key` | `object` | - | +| `duplicate-parent-key.default` | `CallableMessage`<[`"resourceName"`, `"keyName"`]\> | - | +| `invalid-action-name` | `object` | - | +| `invalid-action-name.default` | `"Action name cannot be empty string."` | "Action name cannot be empty string." | +| `not-key-type` | `object` | - | +| `not-key-type.default` | `"Cannot copy keys from a non-key type (KeysOf or ParentKeysOf)"` | "Cannot copy keys from a non-key type (KeysOf or ParentKeysOf)" | +| `resource-missing-error` | `object` | - | +| `resource-missing-error.default` | `CallableMessage`<[`"modelName"`]\> | - | +| `resource-missing-key` | `object` | - | +| `resource-missing-key.default` | `CallableMessage`<[`"modelName"`]\> | - | +| `shared-route-unspecified-action-name` | `object` | - | +| `shared-route-unspecified-action-name.default` | `CallableMessage`<[`"decoratorName"`]\> | - | diff --git a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/namespace.md b/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/namespace.md deleted file mode 100644 index 014e97e58..000000000 --- a/packages/website/versioned_docs/version-latest/libraries/rest/reference/js-api/variables/namespace.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -jsApi: true -title: "[V] namespace" - ---- -```ts -const namespace: "TypeSpec.Rest" = "TypeSpec.Rest"; -``` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$attribute.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$attribute.md index 986814e37..b43cec964 100644 --- a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$attribute.md +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$attribute.md @@ -7,6 +7,8 @@ title: "[F] $attribute" function $attribute(context, target): void ``` +Specify that the target property should be encoded as an XML attribute instead of node. + ## Parameters | Parameter | Type | diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$name.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$name.md index f64a17ad6..9fd331e4c 100644 --- a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$name.md +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/functions/$name.md @@ -10,6 +10,9 @@ function $name( name): void ``` +Provide the name of the XML element or attribute. This means the same thing as + `@encodedName("application/xml", value)` + ## Parameters | Parameter | Type | diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/index.md index f445ed290..8d831cbf2 100644 --- a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/index.md @@ -10,8 +10,17 @@ title: "[P] JS API" ## Type Aliases +- [AttributeDecorator](type-aliases/AttributeDecorator.md) +- [NameDecorator](type-aliases/NameDecorator.md) +- [NsDeclarationsDecorator](type-aliases/NsDeclarationsDecorator.md) +- [NsDecorator](type-aliases/NsDecorator.md) +- [UnwrappedDecorator](type-aliases/UnwrappedDecorator.md) - [XmlEncoding](type-aliases/XmlEncoding.md) +## Variables + +- [$lib](variables/$lib.md) + ## Functions - [$attribute](functions/$attribute.md) 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 4f5b1e870..2c5c2a1cd 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 @@ -3,6 +3,8 @@ jsApi: true title: "[I] XmlEncodeData" --- +Xml Encoding information. + ## Extends - `EncodeData` @@ -11,5 +13,5 @@ title: "[I] XmlEncodeData" | 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` | +| `encoding?` | `string` | Encoding | `EncodeData.encoding` | +| `type` | `Scalar` | Encoding target type.(e.g. string) | `EncodeData.type` | diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlNamespace.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlNamespace.md index 62831a10a..c7db5376d 100644 --- a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlNamespace.md +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/interfaces/XmlNamespace.md @@ -3,9 +3,11 @@ jsApi: true title: "[I] XmlNamespace" --- +Represents an XML namespace. + ## Properties -| Property | Modifier | Type | -| ------ | ------ | ------ | -| `namespace` | `readonly` | `string` | -| `prefix` | `readonly` | `string` | +| Property | Modifier | Type | Description | +| ------ | ------ | ------ | ------ | +| `namespace` | `readonly` | `string` | Namespace name | +| `prefix` | `readonly` | `string` | Namespace prefix | diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/AttributeDecorator.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/AttributeDecorator.md new file mode 100644 index 000000000..060b21ef4 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/AttributeDecorator.md @@ -0,0 +1,46 @@ +--- +jsApi: true +title: "[T] AttributeDecorator" + +--- +```ts +type AttributeDecorator: (context, target) => void; +``` + +Specify that the target property should be encoded as an XML attribute instead of node. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `context` | `DecoratorContext` | +| `target` | `ModelProperty` | + +## Returns + +`void` + +## Examples + +```tsp +model Blob { + id: string; +} +``` + +```xml + + abcdef + +``` + +```tsp +model Blob { + @attribute id: string; +} +``` + +```xml + + +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NameDecorator.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NameDecorator.md new file mode 100644 index 000000000..70c36adfd --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NameDecorator.md @@ -0,0 +1,42 @@ +--- +jsApi: true +title: "[T] NameDecorator" + +--- +```ts +type NameDecorator: (context, target, name) => void; +``` + +Provide the name of the XML element or attribute. This means the same thing as + `@encodedName("application/xml", value)` + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `context` | `DecoratorContext` | - | +| `target` | `Type` | - | +| `name` | `string` | The name of the XML element or attribute | + +## Returns + +`void` + +## Example + +```tsp +@name("XmlBook") +model Book { + @name("XmlId") id: string; + @encodedName("application/xml", "XmlName") name: string; + content: string; +} +``` + +```xml + + string + string + string + +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDeclarationsDecorator.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDeclarationsDecorator.md new file mode 100644 index 000000000..3d9f297e1 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDeclarationsDecorator.md @@ -0,0 +1,21 @@ +--- +jsApi: true +title: "[T] NsDeclarationsDecorator" + +--- +```ts +type NsDeclarationsDecorator: (context, target) => void; +``` + +Mark an enum as declaring XML namespaces. See `@ns` + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `context` | `DecoratorContext` | +| `target` | `Enum` | + +## Returns + +`void` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDecorator.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDecorator.md new file mode 100644 index 000000000..f35fce7a0 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/NsDecorator.md @@ -0,0 +1,53 @@ +--- +jsApi: true +title: "[T] NsDecorator" + +--- +```ts +type NsDecorator: (context, target, ns, prefix?) => void; +``` + +Specify the XML namespace for this element. It can be used in 2 different ways: +1. `@ns("http://www.example.com/namespace", "ns1")` - specify both namespace and prefix +2. `@Xml.ns(Namespaces.ns1)` - pass a member of an enum decorated with `@nsDeclaration` + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `context` | `DecoratorContext` | - | +| `target` | `Type` | - | +| `ns` | `Type` | The namespace URI or a member of an enum decorated with `@nsDeclaration`. | +| `prefix`? | `string` | The namespace prefix. Required if the namespace parameter was passed as a string. | + +## Returns + +`void` + +## Examples + +```tsp +@ns( "https://example.com/ns1", "ns1") +model Foo { + @ns("https://example.com/ns1", "ns1") + bar: string + @ns("https://example.com/ns2", "ns2") + bar: string +} +``` + +```tsp +@Xml.nsDeclarations +enum Namespaces { + ns1: "https://example.com/ns1", + ns2: "https://example.com/ns2" +} + +@Xml.ns(Namespaces.ns1) +model Foo { + @Xml.ns(Namespaces.ns1) + bar: string + @Xml.ns(Namespaces.ns2) + bar: string +} +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/UnwrappedDecorator.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/UnwrappedDecorator.md new file mode 100644 index 000000000..ff60cd5b4 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/type-aliases/UnwrappedDecorator.md @@ -0,0 +1,80 @@ +--- +jsApi: true +title: "[T] UnwrappedDecorator" + +--- +```ts +type UnwrappedDecorator: (context, target) => void; +``` + +Specify that the target property shouldn't create a wrapper node. This can be used to flatten list nodes into the model node or to include raw text in the model node. +It cannot be used with `@attribute`. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `context` | `DecoratorContext` | +| `target` | `ModelProperty` | + +## Returns + +`void` + +## Examples + +```tsp +model Pet { + tags: Tag[]; +} +``` + +```xml + + + + string + + + +``` + +```tsp +model Pet { + @unwrapped tags: Tag[]; +} +``` + +```xml + + + string + + +``` + +```tsp +model BlobName { + content: string; +} +``` + +```xml + + + abcdef + + +``` + +```tsp +model BlobName { + @unwrapped content: string; +} +``` + +```xml + + abcdef + +``` diff --git a/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/variables/$lib.md b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/variables/$lib.md new file mode 100644 index 000000000..37faa6468 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/libraries/xml/reference/js-api/variables/$lib.md @@ -0,0 +1,25 @@ +--- +jsApi: true +title: "[V] $lib" + +--- +```ts +const $lib: TypeSpecLibrary, "attribute" | "unwrapped" | "ns" | "nsDeclaration">; +``` + +TypeSpec Xml Library Definition + +## Type declaration + +| Name | Type | Default value | +| ------ | ------ | ------ | +| `invalid-ns-declaration-member` | `object` | - | +| `invalid-ns-declaration-member.default` | `CallableMessage`<[`"name"`]\> | - | +| `ns-enum-not-declaration` | `object` | - | +| `ns-enum-not-declaration.default` | `"Enum member used as namespace must be part of an enum marked with @nsDeclaration."` | "Enum member used as namespace must be part of an enum marked with @nsDeclaration." | +| `ns-missing-prefix` | `object` | - | +| `ns-missing-prefix.default` | `"When using a string namespace you must provide a prefix as the 2nd argument."` | "When using a string namespace you must provide a prefix as the 2nd argument." | +| `ns-not-uri` | `object` | - | +| `ns-not-uri.default` | `"Namespace namespace is not a valid URI."` | - | +| `prefix-not-allowed` | `object` | - | +| `prefix-not-allowed.default` | `"@ns decorator cannot have the prefix parameter set when using an enum member."` | "@ns decorator cannot have the prefix parameter set when using an enum member." | diff --git a/packages/website/versioned_docs/version-latest/release-notes/release-2024-09-10.md b/packages/website/versioned_docs/version-latest/release-notes/release-2024-09-10.md new file mode 100644 index 000000000..9fc289040 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/release-notes/release-2024-09-10.md @@ -0,0 +1,62 @@ +--- +title: 0.60 - September 2024 +--- + +## Features + +### @typespec/compiler + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Add new way to define decorator implementation with `$decorators` export. + +```ts +export const $decorators = { + "TypeSpec.OpenAPI": { + useRef: $useRef, + oneOf: $oneOf, + }, +}; +``` + +- [#4148](https://github.com/microsoft/typespec/pull/4148) Diagnostics logged to the terminal now have a clickable hyperlink to the diagnostic documentation url if applicable. +- [#4141](https://github.com/microsoft/typespec/pull/4141) Diagnostic code in IDE now link to the linter rule documentation url if applicable +- [#4357](https://github.com/microsoft/typespec/pull/4357) Improvements to type relation errors: Show stack when it happens in a nested property otherwise show up in the correct location. + +## Bug Fixes + +### @typespec/compiler + +- [#4381](https://github.com/microsoft/typespec/pull/4381) Fix Semantic walker doesn't fire exitOperation or exitModelProperty +- [#4146](https://github.com/microsoft/typespec/pull/4146) Fix model expression defined in alias will resolve its namespace from the namespace where the alias was declared +- [#4147](https://github.com/microsoft/typespec/pull/4147) Fix examples with models using `extends` +- [#4144](https://github.com/microsoft/typespec/pull/4144) Fix: Model and union expression in template were not considered as template instances +- [#4135](https://github.com/microsoft/typespec/pull/4135) Fix numeric 0 stringify producing 0.0 +- [#4064](https://github.com/microsoft/typespec/pull/4064) IDE: Formatting command will use prettier config if provided over the editor's configuration. +- [#4089](https://github.com/microsoft/typespec/pull/4089) Fix tmlanguage for named type argument in type reference. +- [#4324](https://github.com/microsoft/typespec/pull/4324) API: Extract source resolution logic into its own source loader + +### @typespec/http + +- [#4322](https://github.com/microsoft/typespec/pull/4322) Use user provided description of model if model has a status code property(detect it as an response envelope) + +### @typespec/versioning + +- [#4145](https://github.com/microsoft/typespec/pull/4145) Fix error when trying to reference types from another sub namespace of a versioned namespace +- [#4179](https://github.com/microsoft/typespec/pull/4179) Add validation to make sure operation params reference models available in the current version +- [#4179](https://github.com/microsoft/typespec/pull/4179) Add validation to make sure types referencing array in union types have compatible versioning. + +### @typespec/openapi3 + +- [#4133](https://github.com/microsoft/typespec/pull/4133) Fix Bug for OpenAPI 3 Emitter crash on `@useAuth({})` +- [#4123](https://github.com/microsoft/typespec/pull/4123) Fix OpenAPI3 union names when declared within a namespace +- [#4216](https://github.com/microsoft/typespec/pull/4216) Fixes issue in tsp-openapi3 that resulted in component schemas and parameters with the same name being merged into a single TypeSpec data type. +- [#4232](https://github.com/microsoft/typespec/pull/4232) Improves tsp-openapi3 model generation from schemas utilizing allOf. Models will now extend an allOf member if it is a schema reference and the only member with a discriminator. Other members will be spread into the model if defined as a schema reference, or have their properties treated as top-level properties if they are an inline-schema. +- [#4149](https://github.com/microsoft/typespec/pull/4149) Updates tsp-openapi3 conversion of OpenAPI3 component schemas to improve handling of enums, unions, scalars, and aliases. + +### @typespec/html-program-viewer + +- [#4353](https://github.com/microsoft/typespec/pull/4353) Fix crash when using anonymous union variant +- [#4136](https://github.com/microsoft/typespec/pull/4136) Fix namespace with the same name conflicting in the tree navigation + +### @typespec/json-schema + +- [#4150](https://github.com/microsoft/typespec/pull/4150) Stop json schema from crashing on unknown scalar and handle `unixTimestamp32` diff --git a/packages/website/versioned_docs/version-latest/standard-library/examples.md b/packages/website/versioned_docs/version-latest/standard-library/examples.md index 85dd97c35..afbfaccff 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/examples.md +++ b/packages/website/versioned_docs/version-latest/standard-library/examples.md @@ -78,14 +78,14 @@ Operation example will not validate additional properties as the applicable para ### Simple operation parameters ```tsp -@example(#{ parameters: #{ name: "Max", age: 3 } }) +@opExample(#{ parameters: #{ name: "Max", age: 3 } }) op write(name: string, age: int32): void; ``` ### Simple operation return types ```tsp -@example(#{ returnType: #{ name: "Max", age: 3 } }) +@opExample(#{ returnType: #{ name: "Max", age: 3 } }) op read(): { name: string; age: int32; @@ -95,7 +95,7 @@ op read(): { ### Specify title and/or description ```tsp -@example( +@opExample( #{ parameters: #{ name: "Max", age: 3 } }, #{ title: "Simple write example", description: "Write a pet" } ) diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encodedName.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encodedName.md deleted file mode 100644 index 32c809b6f..000000000 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/functions/$encodedName.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -jsApi: true -title: "[F] $encodedName" - ---- -```ts -function $encodedName( - context, - target, - mimeType, - name): void -``` - -## Parameters - -| Parameter | Type | -| ------ | ------ | -| `context` | [`DecoratorContext`](../interfaces/DecoratorContext.md) | -| `target` | [`Type`](../type-aliases/Type.md) | -| `mimeType` | `string` | -| `name` | `string` | - -## Returns - -`void` diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/index.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/index.md index 2d3181313..318d05118 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/index.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/index.md @@ -65,6 +65,7 @@ Renames and re-exports [formatIdentifier](functions/formatIdentifier.md) - [DecoratorDefinition](interfaces/DecoratorDefinition.md) - [DecoratorExpressionNode](interfaces/DecoratorExpressionNode.md) - [DecoratorFunction](interfaces/DecoratorFunction.md) +- [DecoratorImplementations](interfaces/DecoratorImplementations.md) - [DecoratorParamDefinition](interfaces/DecoratorParamDefinition.md) - [DecoratorValidator](interfaces/DecoratorValidator.md) - [DeprecatedDirective](interfaces/DeprecatedDirective.md) @@ -393,7 +394,6 @@ Renames and re-exports [formatIdentifier](functions/formatIdentifier.md) - [$discriminator](functions/$discriminator.md) - [$doc](functions/$doc.md) - [$encode](functions/$encode.md) -- [$encodedName](functions/$encodedName.md) - [$error](functions/$error.md) - [$errorsDoc](functions/$errorsDoc.md) - [$example](functions/$example.md) diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/DecoratorImplementations.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/DecoratorImplementations.md new file mode 100644 index 000000000..d0d9e3ddc --- /dev/null +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/DecoratorImplementations.md @@ -0,0 +1,21 @@ +--- +jsApi: true +title: "[I] DecoratorImplementations" + +--- +Type for the $decorators export from libraries. + +## Example + +``` +export const $decorators = { + "Azure.Core": { + flags: $flags, + "foo-bar": fooBarDecorator + } +} +``` + +## Indexable + + \[`namespace`: `string`\]: `object` diff --git a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/ProcessedLog.md b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/ProcessedLog.md index 3d6f20397..3e2bc029f 100644 --- a/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/ProcessedLog.md +++ b/packages/website/versioned_docs/version-latest/standard-library/reference/js-api/interfaces/ProcessedLog.md @@ -5,9 +5,10 @@ title: "[I] ProcessedLog" --- ## Properties -| Property | Type | -| ------ | ------ | -| `code?` | `string` | -| `level` | [`LogLevel`](../type-aliases/LogLevel.md) | -| `message` | `string` | -| `sourceLocation?` | [`SourceLocation`](SourceLocation.md) | +| Property | Type | Description | +| ------ | ------ | ------ | +| `code?` | `string` | - | +| `level` | [`LogLevel`](../type-aliases/LogLevel.md) | - | +| `message` | `string` | - | +| `sourceLocation?` | [`SourceLocation`](SourceLocation.md) | - | +| `url?` | `string` | Documentation for the error code. | diff --git a/packages/xml/CHANGELOG.md b/packages/xml/CHANGELOG.md index f282943ba..2f0ed0f28 100644 --- a/packages/xml/CHANGELOG.md +++ b/packages/xml/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog - @typespec/xml +## 0.60.0 + +### Features + +- [#4139](https://github.com/microsoft/typespec/pull/4139) Internals: Migrate to new api for declaring decorator implementation + + ## 0.59.0 ### Bump dependencies diff --git a/packages/xml/package.json b/packages/xml/package.json index 68ac7d7a0..28dc9c8d1 100644 --- a/packages/xml/package.json +++ b/packages/xml/package.json @@ -1,6 +1,6 @@ { "name": "@typespec/xml", - "version": "0.59.0", + "version": "0.60.0", "author": "Microsoft Corporation", "description": "TypeSpec library providing xml bindings", "homepage": "https://typespec.io",