Reference doc generation (#1415)
This commit is contained in:
Timothee Guerin
GitHub
Родитель
f4fc4fa848
Коммит
9b6a32d8f4
|
|
@ -28,3 +28,6 @@ packages/samples/local-cadl/test.cadl
|
|||
packages/website/build/
|
||||
|
||||
spec.emu.html
|
||||
|
||||
# Auto generated reference docs.
|
||||
docs/**/reference/
|
||||
|
|
|
|||
|
|
@ -136,6 +136,14 @@ reviewed, checked-in versions. If your PR would change the generated output,
|
|||
run this command to regenerate any samples and check those files in with
|
||||
your PR. Carefully review whether the changes are intentional.
|
||||
|
||||
## Regenerate Reference Docs
|
||||
|
||||
```bash
|
||||
rush regen-docs
|
||||
```
|
||||
|
||||
PR validation will ensure that reference docs are up to date.
|
||||
|
||||
# Using VS Code
|
||||
|
||||
## Recommended extensions
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"changes": [
|
||||
{
|
||||
"packageName": "@cadl-lang/compiler",
|
||||
"comment": "Type graph navigation navigate decorators",
|
||||
"type": "none"
|
||||
}
|
||||
],
|
||||
"packageName": "@cadl-lang/compiler"
|
||||
}
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"changes": [
|
||||
{
|
||||
"packageName": "@cadl-lang/rest",
|
||||
"comment": "",
|
||||
"type": "none"
|
||||
}
|
||||
],
|
||||
"packageName": "@cadl-lang/rest"
|
||||
}
|
||||
|
|
@ -48,6 +48,12 @@
|
|||
"summary": "(CUSTOM) Checks formatting of all code with with Prettier.",
|
||||
"shellCommand": "node eng/scripts/check-format.js"
|
||||
},
|
||||
{
|
||||
"commandKind": "global",
|
||||
"name": "regen-docs",
|
||||
"summary": "(CUSTOM) Regenerate the reference docs.",
|
||||
"shellCommand": "node eng/scripts/regen-docs.js"
|
||||
},
|
||||
{
|
||||
"commandKind": "global",
|
||||
"name": "regen-samples",
|
||||
|
|
|
|||
|
|
@ -33,6 +33,7 @@ specifiers:
|
|||
'@rush-temp/openapi3': file:./projects/openapi3.tgz
|
||||
'@rush-temp/playground': file:./projects/playground.tgz
|
||||
'@rush-temp/prettier-plugin-cadl': file:./projects/prettier-plugin-cadl.tgz
|
||||
'@rush-temp/ref-doc': file:./projects/ref-doc.tgz
|
||||
'@rush-temp/rest': file:./projects/rest.tgz
|
||||
'@rush-temp/samples': file:./projects/samples.tgz
|
||||
'@rush-temp/spec': file:./projects/spec.tgz
|
||||
|
|
@ -153,6 +154,7 @@ dependencies:
|
|||
'@rush-temp/openapi3': file:projects/openapi3.tgz
|
||||
'@rush-temp/playground': file:projects/playground.tgz_rollup@3.4.0
|
||||
'@rush-temp/prettier-plugin-cadl': file:projects/prettier-plugin-cadl.tgz
|
||||
'@rush-temp/ref-doc': file:projects/ref-doc.tgz
|
||||
'@rush-temp/rest': file:projects/rest.tgz
|
||||
'@rush-temp/samples': file:projects/samples.tgz
|
||||
'@rush-temp/spec': file:projects/spec.tgz
|
||||
|
|
@ -13912,7 +13914,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/bundler.tgz:
|
||||
resolution: {integrity: sha512-Zas1SNEIhL0YfKH7+HBYCUHfEkLA9023XS/5kgSZpeXQbXQ7QmJBzlskJqQ61NsQhghiohGhxq6DgO4b19Qc8A==, tarball: file:projects/bundler.tgz}
|
||||
resolution: {integrity: sha512-iNU5tBmY0B7V0oCEKiIz4xX6z1A1tJdmcSFcyH/WQNWUaE1wDvGsgOCTS27EoRKIFwXyfSRTznrmjMNZL2ODig==, tarball: file:projects/bundler.tgz}
|
||||
name: '@rush-temp/bundler'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -13942,13 +13944,13 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/cadl-vs.tgz:
|
||||
resolution: {integrity: sha512-fs8/o0L0nDCQWeWUKJrFd5+GLW7KdjTV5dXRgLqN98E1QRhGkm8iha5AMPE/6eRp/64Ct3wmncFuny/7LHWUCg==, tarball: file:projects/cadl-vs.tgz}
|
||||
resolution: {integrity: sha512-zbbCNHwIdI3MGU9IlMDMJirbb3pWMXtvmKNgdtZ4EhKlgNnqFuYbkpszcCoGAUHuuLj2Vt+mX+Kkb1DAUSiWmQ==, tarball: file:projects/cadl-vs.tgz}
|
||||
name: '@rush-temp/cadl-vs'
|
||||
version: 0.0.0
|
||||
dev: false
|
||||
|
||||
file:projects/cadl-vscode.tgz:
|
||||
resolution: {integrity: sha512-9fY7oFKFqiOROhGf3NzEnIMUbPpzIxpDSxpaW0WZfOInGkYcnjO7Vx4D1nIg7w+6QX2xXtcWewwiFmGykCHGXg==, tarball: file:projects/cadl-vscode.tgz}
|
||||
resolution: {integrity: sha512-Hx5gSreeOGr94sQgxrHEvnQEUEE7Adjj8TH4wW2ZWPK0zuG0JADZJ77/2S9omZraZa5/j/XHQ8eKF7UhzaL52g==, tarball: file:projects/cadl-vscode.tgz}
|
||||
name: '@rush-temp/cadl-vscode'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -13974,7 +13976,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/compiler.tgz:
|
||||
resolution: {integrity: sha512-zrMl3iSx+8WvKkStlpyAUF/kdhu3kk2gnsr7H6uLjWqNOWwg+NaXrMDM19vhxIR7XKVZtIXIrw1ITv9x5ACpBA==, tarball: file:projects/compiler.tgz}
|
||||
resolution: {integrity: sha512-BWngEUu+JpEbLhWkvoUYsNI2TpqcwcQoBAmnc5GOUelbO16cVHi/kSwIM19uDAGogOo5oL9U9Y86QI7gvr5KJQ==, tarball: file:projects/compiler.tgz}
|
||||
name: '@rush-temp/compiler'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14041,7 +14043,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/eslint-plugin.tgz:
|
||||
resolution: {integrity: sha512-/wEwCFQC2RJNNkkDiwjIu6sgTtTSbibTuZgzvAdG+vneQl1BjmhCCx9+tqWFfQ7JxrVhBvbmL+WhB0C2xsJGjg==, tarball: file:projects/eslint-plugin.tgz}
|
||||
resolution: {integrity: sha512-JpaB9Vgn/wscM771iqqV7a0yquhUwfspuFfHnatJaNhNV4mB09q1oyOjz7TxdG3vBUwCrffFgQ937LEu7CHIIA==, tarball: file:projects/eslint-plugin.tgz}
|
||||
name: '@rush-temp/eslint-plugin'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14061,7 +14063,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/html-program-viewer.tgz:
|
||||
resolution: {integrity: sha512-q+WFrROhypxmttKwtz5sUF5Dh7c4KxN+ZKECToIJv+7txmIgipbcGnK7MMCI426Olu2hxfO8XRQkxnrCpsHCHQ==, tarball: file:projects/html-program-viewer.tgz}
|
||||
resolution: {integrity: sha512-Ub9GPx4YmRJejV03vXoeVuyyf5N6nQjtUD8XZqlDclkvTLXaL1CNHYlrJrPkGRSzexivEXU89SwO0PUgq3YT6g==, tarball: file:projects/html-program-viewer.tgz}
|
||||
name: '@rush-temp/html-program-viewer'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14088,7 +14090,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/internal-build-utils.tgz:
|
||||
resolution: {integrity: sha512-0wkPbr6zoPIzD7T+nehxZXFb0JJjYHK4RV2dOP+uJuAp6Uf7u68qRc0gPfYcfjgaTzUpP45ZAJEK53bUxvDTIA==, tarball: file:projects/internal-build-utils.tgz}
|
||||
resolution: {integrity: sha512-w400v0Mf9toryfYRMk/AODGT0SjqC1HIA88KxhQRkYLZSi3xnNG7QOxD8sF0aTN2nm5VaF8eaPmRUHgWL65dFg==, tarball: file:projects/internal-build-utils.tgz}
|
||||
name: '@rush-temp/internal-build-utils'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14113,7 +14115,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/library-linter.tgz:
|
||||
resolution: {integrity: sha512-3IFwbQYAcjfiVmjflD7TTNqETF42D33ZNEWCgz4fA6Ti1Q5fFUZoICOqrs5t0SOnjHmPXFZl8s9jMylmWrez5Q==, tarball: file:projects/library-linter.tgz}
|
||||
resolution: {integrity: sha512-p1E9mXCf+vYvBn6I88vABZZOqIKzvgAAxNMlkoaBqeSTJwSIEKU5Ys3kjLQ8ZaLj8N0tifTid0dLwOzAa9nCvg==, tarball: file:projects/library-linter.tgz}
|
||||
name: '@rush-temp/library-linter'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14131,7 +14133,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/lint.tgz:
|
||||
resolution: {integrity: sha512-eA3Lw3nCmSe0lfxkE+usuxpPqETt8v+aI4NmEyOS7AtDsSQUBfydfhfJXfzgCD5nBVYTaPZoSozEqPCXFHPcxg==, tarball: file:projects/lint.tgz}
|
||||
resolution: {integrity: sha512-TNb3n2vI13wPwGzjcZkHVBTrxtiupAJ3/7t5iSg7CzsHeF1jcEb3i24MqIjd+bWQiLjTyKOp5Oo8/BWiODvgpw==, tarball: file:projects/lint.tgz}
|
||||
name: '@rush-temp/lint'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14149,7 +14151,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/migrate.tgz:
|
||||
resolution: {integrity: sha512-TkrCkt1/vCz/OFoqCIz613PlJJIOS3ZcvicpSQpZzcIh+R2p4iGHI3S/wlF/LfTyHJB4QctP/A0wHJEm6blXaQ==, tarball: file:projects/migrate.tgz}
|
||||
resolution: {integrity: sha512-GsgpXk4ihM9HUadmAkJSMCsP+au1mb26aHoSpgf2xL1McBcXujOvcdvaYauBGBVQunRqsmEophFQCQKUa2hiSQ==, tarball: file:projects/migrate.tgz}
|
||||
name: '@rush-temp/migrate'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14169,7 +14171,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/openapi.tgz:
|
||||
resolution: {integrity: sha512-Q1H5xFEpWcLHJ3PJlCdHbBp9je+9sVa+96ZJ6I0F5m23PvGNvJfcekmFzc/AoM21SWEnO6cfnEOdCGsuboTkJA==, tarball: file:projects/openapi.tgz}
|
||||
resolution: {integrity: sha512-NCF6iHsLvunerEPPSxQkiUOFt+LfIQWW9rau8iOws+zuHLUeosFFBAUWLW/AFIIIiTpnlmmfUQllRG4cGFQQFQ==, tarball: file:projects/openapi.tgz}
|
||||
name: '@rush-temp/openapi'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14187,7 +14189,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/openapi3.tgz:
|
||||
resolution: {integrity: sha512-68WcI6vVPvWyV1vlsNG53vaT/CAQr53gTWNOUJusWA5s3MrD8i5hQiH2esHp2PoVKb6bAbUAkGU9M8/R7eRVtQ==, tarball: file:projects/openapi3.tgz}
|
||||
resolution: {integrity: sha512-zT+tI79GJzM/4ij1ZZsfL3nLAlcOX2vTw52wf739w3uTJgFH5NnNprfQXqD9TH7HUsnqmCs1dvUnVucgl2Ie9g==, tarball: file:projects/openapi3.tgz}
|
||||
name: '@rush-temp/openapi3'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14205,7 +14207,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/playground.tgz_rollup@3.4.0:
|
||||
resolution: {integrity: sha512-8N8Gdll+hadyzMGh1q1NEa+Pub14PaWFOBHqUvSyhFxQAr+sXtftOQHDFtWIAzVg6UH6NPlTOFzlNmKyB1EI5A==, tarball: file:projects/playground.tgz}
|
||||
resolution: {integrity: sha512-ytN5l7hnIIvUcfyBHkxAmqTqU/4Jlgz75/oQ6SOraGFYatHk2e1XTrXajN6X4y7g43rihYnDnHUiNQ59fJzoaA==, tarball: file:projects/playground.tgz}
|
||||
id: file:projects/playground.tgz
|
||||
name: '@rush-temp/playground'
|
||||
version: 0.0.0
|
||||
|
|
@ -14257,7 +14259,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/prettier-plugin-cadl.tgz:
|
||||
resolution: {integrity: sha512-yvD+tx564wjMCd3iomKo7kzzfJ5G5TWk5DhcwGbeLEN14DMjtr3q5ZIBDOc8IEeGJR+IHQVT/eAL3BHv7BN6gQ==, tarball: file:projects/prettier-plugin-cadl.tgz}
|
||||
resolution: {integrity: sha512-aPsVRDlfTmqpz1bnhbd+LkKT+t+gCPp6hdf7Ngll1ruD2dmh+jlnHXTE0DtlgzqrtY1DpetEYfPrV9FT/XfquA==, tarball: file:projects/prettier-plugin-cadl.tgz}
|
||||
name: '@rush-temp/prettier-plugin-cadl'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14274,8 +14276,28 @@ packages:
|
|||
- supports-color
|
||||
dev: false
|
||||
|
||||
file:projects/ref-doc.tgz:
|
||||
resolution: {integrity: sha512-St2W9ZbpDQdrcyFAsSekMnXJfwMScejDFAJ6CHBUsdi+fqfiATZEyVLXm+ovEx1Hg6q3qwcOL3KQj+hjx1yRww==, tarball: file:projects/ref-doc.tgz}
|
||||
name: '@rush-temp/ref-doc'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
'@types/mocha': 10.0.0
|
||||
'@types/node': 18.11.9
|
||||
'@types/prettier': 2.6.0
|
||||
c8: 7.12.0
|
||||
eslint: 8.28.0
|
||||
mocha: 10.1.0
|
||||
mocha-junit-reporter: 2.2.0_mocha@10.1.0
|
||||
mocha-multi-reporters: 1.5.1_mocha@10.1.0
|
||||
prettier: 2.7.1
|
||||
rimraf: 3.0.2
|
||||
typescript: 4.9.3
|
||||
transitivePeerDependencies:
|
||||
- supports-color
|
||||
dev: false
|
||||
|
||||
file:projects/rest.tgz:
|
||||
resolution: {integrity: sha512-TLqBu6PLLgLyacH6oo7i/IcYMW1XiVgRUvh1OrBy/GaylTg7lk6jnbHij1GnI/F8Lhn741uklExQB7+0ImcGuQ==, tarball: file:projects/rest.tgz}
|
||||
resolution: {integrity: sha512-q/VjAdNeTDOKBSzK1wdC3ngdLkDBeBqiPX+JdyYcDs3A24Bb5paL2ycznWNMjV4+I8MXWGgdUtrCcmNgTYhzUQ==, tarball: file:projects/rest.tgz}
|
||||
name: '@rush-temp/rest'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14293,7 +14315,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/samples.tgz:
|
||||
resolution: {integrity: sha512-YnpXG1jCayih6Ep0j7n+pDqqREKi/Ef8NuOKiC/rmbUJmTddlrr5IYGUhC7X5XQL2QbjEQ7e+G5u1GzEh3IPdg==, tarball: file:projects/samples.tgz}
|
||||
resolution: {integrity: sha512-DeaQnVZZK42PebXFIxsy0IhGkPqvtVxA3a/6P76iiwMkRk+o5e1bq5RIFxzfgC8dhO8suBYljsg+v88p+mknvA==, tarball: file:projects/samples.tgz}
|
||||
name: '@rush-temp/samples'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14303,7 +14325,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/spec.tgz:
|
||||
resolution: {integrity: sha512-fs2edFmGO9Q27q5qRMyOZwHLUleL1HmdUcWdDJahLwzduLR6DGHPDZIWV0b/FuEVZiMKIQIrcZ4380rgCvUHeA==, tarball: file:projects/spec.tgz}
|
||||
resolution: {integrity: sha512-YyYDVv6nR4ZKFGXhNAmEXNDbGnZC+QIt2SOzxFdPzx3nY4JzdH75neT0OZBEQAQukaIj3MV7lgUZ96wREv63aA==, tarball: file:projects/spec.tgz}
|
||||
name: '@rush-temp/spec'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14318,7 +14340,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/tmlanguage-generator.tgz:
|
||||
resolution: {integrity: sha512-tdF/mqINvkxrqFOFAiLeA43nVRytGJryDFjBfmeb7S54lU71WZLKzd+GRX+lvBJW64d+HUNjarHg8oHOzsftqw==, tarball: file:projects/tmlanguage-generator.tgz}
|
||||
resolution: {integrity: sha512-DejsT0k6kmu6GmONzDQw96JqgEIYqWYjeELVamATe1yDkshqoPDttcj2jnAYWLT1yl+COtWynzb6pTNdUJx6tw==, tarball: file:projects/tmlanguage-generator.tgz}
|
||||
name: '@rush-temp/tmlanguage-generator'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14334,7 +14356,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/versioning.tgz:
|
||||
resolution: {integrity: sha512-XwxMKvo9BWq0Vr2Ndcfw+mXDlIE0r5Zw58UdgJ/u3L0NSq8zRTC+uibFKFT2gH7ZF9xOPMacFk3yxbTMIlIkAg==, tarball: file:projects/versioning.tgz}
|
||||
resolution: {integrity: sha512-bz0OicVBCdBvQXrFPOcDxLwsxJHsPo0+1jJ1Yranwm++GMYRyPsLy2MHZ9MQPLx/v9NTVQWGT6SxgrWGwuN8CQ==, tarball: file:projects/versioning.tgz}
|
||||
name: '@rush-temp/versioning'
|
||||
version: 0.0.0
|
||||
dependencies:
|
||||
|
|
@ -14352,7 +14374,7 @@ packages:
|
|||
dev: false
|
||||
|
||||
file:projects/website.tgz_@types+react@18.0.25:
|
||||
resolution: {integrity: sha512-NeBMw7IYi+n4kOBMuAZsbPvaGlYqva9g+JiJFQ6uusRaxFR6Hw6IvxvNvkbvLP4CGPsXCrxyeORksijGoFSYTg==, tarball: file:projects/website.tgz}
|
||||
resolution: {integrity: sha512-3GsmNKLHFMiEtrHwU5lN7UnZSRtZ9f3eFS2/qq9ERMRhDdTiTX6ywOb9iLyVboSSenPIQ6vw7dzrqS/Ti0eDaQ==, tarball: file:projects/website.tgz}
|
||||
id: file:projects/website.tgz
|
||||
name: '@rush-temp/website'
|
||||
version: 0.0.0
|
||||
|
|
|
|||
|
|
@ -1,107 +0,0 @@
|
|||
---
|
||||
title: Decorators
|
||||
---
|
||||
|
||||
# OpenAPI Decorators
|
||||
|
||||
- [`@defaultResponse`](#defaultresponse)
|
||||
- [`@extension`](#extension)
|
||||
- [`@oneOf`](#oneof)
|
||||
- [`@externalDocs`](#externaldocs)
|
||||
- [`@operationId`](#operationid)
|
||||
- [`@useRef`](#useref)
|
||||
|
||||
## `@defaultResponse`
|
||||
|
||||
**IMPORTANT This is to be used on `NON-ERROR` responses that cover all the other status codes. If you are looking to represent an error use [`@error`](https://microsoft.github.io/cadl/docs/standard-library/built-in-decorators/#error)**
|
||||
|
||||
Decorator that can be used on a response model to specify the `default` status code that OpenAPI allow.
|
||||
|
||||
```cadl
|
||||
@defaultResponse
|
||||
model MyNonErrorResponse {}
|
||||
|
||||
op foo(): MyNonErrorResponse;
|
||||
```
|
||||
|
||||
## `@extension`
|
||||
|
||||
This decorator lets you specify custom key(starting with `x-`) value pair that will be added to the OpenAPI document.
|
||||
[OpenAPI reference on extensions](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#specificationExtensions)
|
||||
|
||||
Arguments:
|
||||
|
||||
| Name | foo | Description |
|
||||
| ------- | ------------ | ---------------------------------------------------------------- |
|
||||
| `key` | **Required** | Extension key. **MUST** start with `x-` |
|
||||
| `value` | **Required** | Value of the extension. Can be an primitive, a tuple or a model. |
|
||||
|
||||
```cadl
|
||||
@extension("x-custom", "MyCustomValue")
|
||||
model Foo {}
|
||||
|
||||
// Value can be an model.
|
||||
@extension(
|
||||
"x-custom",
|
||||
{
|
||||
some: "value",
|
||||
}
|
||||
)
|
||||
model Foo {}
|
||||
```
|
||||
|
||||
## `@externalDocs`
|
||||
|
||||
Decorator that can be used to provide the `externalDocs` property on OpenAPI elements.
|
||||
[OpenAPI spec for externalDocs](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#externalDocumentationObject)
|
||||
|
||||
Arguments:
|
||||
|
||||
| Name | foo | Description |
|
||||
| ------------- | ------------ | -------------------------------- |
|
||||
| `url` | **Required** | Url for the external docs |
|
||||
| `description` | **Optional** | Description of the documentation |
|
||||
|
||||
```cadl
|
||||
@externalDocs("https://example.com", "More info there")
|
||||
model Foo {}
|
||||
```
|
||||
|
||||
### @oneOf
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@oneOf()
|
||||
```
|
||||
|
||||
`@oneOf`emits `oneOf` keyword for a union type in the resulting OpenAPI 3.0 specification. It indicates that the value of union type can only contain exactly one of the subschemas.
|
||||
|
||||
`@oneOf` can only be applied to a union types.
|
||||
|
||||
## `@operationId`
|
||||
|
||||
Decorator that can be used on an operation to specify the `operationId` field in OpenAPI. If this is not provided the `operationId` will be the cadl operation name.
|
||||
|
||||
Arguments:
|
||||
|
||||
| Name | foo | Description |
|
||||
| ------ | ------------ | ------------------- |
|
||||
| `opId` | **Required** | Id of the operation |
|
||||
|
||||
```cadl
|
||||
@operationId("custom_Foo")
|
||||
op foo(): string;
|
||||
```
|
||||
|
||||
### @useRef
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@useRef(urlString)
|
||||
```
|
||||
|
||||
`@useRef`
|
||||
|
||||
`@useRef` is used to replace the Cadl model type in emitter output with a pre-existing named OpenAPI schema.
|
||||
|
|
@ -8,7 +8,7 @@ The OpenAPI emitter converts Cadl language elements into their natural OpenAPI e
|
|||
|
||||
## Servers
|
||||
|
||||
If the Cadl file contains an [(Http) `@server` decorator](../rest/decorators.md#server)
|
||||
If the Cadl file contains an [(Http) `@server` decorator](../rest/reference/decorators.md#@Cadl.Http.server)
|
||||
the OpenAPI emitter will generate a `servers` object with the server URL, description, and variables specified in the decorator.
|
||||
|
||||
You can specify multiple `@server` decorators to obtain multiple entries in the `servers` object.
|
||||
|
|
@ -23,8 +23,8 @@ The path for the operation comes from the [(Http) `@route` decorator][http-route
|
|||
The `@route` decorator can also be specified on a namespace and/or an interface (group of operations).
|
||||
When specified, the route for the enclosing namespace(s) and interface are prefixed to the operation route.
|
||||
|
||||
[http-verb-decorators]: ../rest/decorators.md#http-verb-decorators
|
||||
[http-route-decorator]: ../rest/decorators.md#routing
|
||||
[http-verb-decorators]: ../rest/reference/decorators.md
|
||||
[http-route-decorator]: ../rest/reference/decorators.md#@Cadl.Http.route
|
||||
|
||||
The fields of the [OpenAPI Operation object][] are set as described below.
|
||||
|
||||
|
|
@ -59,8 +59,8 @@ A parameter without one of these decorators is assumed to be passed in the reque
|
|||
The request body parameter can also be explicitly decorated with an [(Http) `@body` decorator][http-body-decorator].
|
||||
In the absence of explicit `@body`, the set of parameters that are not marked `@header`, `@query`, or `@path` form the request body.
|
||||
|
||||
[http-parameter-decorators]: ../rest/decorators.md#data-types
|
||||
[http-body-decorator]: ../rest/decorators.md#body
|
||||
[http-parameter-decorators]: ../rest/reference/decorators.md#data-types
|
||||
[http-body-decorator]: ../rest/reference/decorators.md#@Cadl.Http.body
|
||||
|
||||
The content of a (built-in) `@doc` decorator on a parameter will be set in the description.
|
||||
|
||||
|
|
@ -85,7 +85,7 @@ When a return type model has a property explicitly decorated with an [(Http) `@b
|
|||
is taken as the response body.
|
||||
In the absence of explicit `@body`, the properties that are not marked `@statusCode` or `@header` form the response body.
|
||||
|
||||
[http-statuscode-decorator]: ../rest/decorators.md#statuscode
|
||||
[http-statuscode-decorator]: ../rest/reference/decorators.md#@Cadl.Http.statuscode
|
||||
[error-decorator]: ../built-in-decorators.md#error
|
||||
|
||||
See also [metadata](../rest/operations.md#metadata) for more advanced details.
|
||||
|
|
@ -106,12 +106,12 @@ deprecated field is set to true.
|
|||
|
||||
### externalDocs
|
||||
|
||||
If the Cadl operation has an [(OpenAPI) `@externalDocs` decorator](./decorators.md#externaldocs) this will produce
|
||||
If the Cadl operation has an [(OpenAPI) `@externalDocs` decorator](./reference/decorators.md#@OpenAPI.externaldocs) this will produce
|
||||
an externalDocs field in the OpenAPI operation.
|
||||
|
||||
### Specification extensions
|
||||
|
||||
Any extensions specified on the Cadl operation with the [(OpenAPI) `@extension` decorator](./decorators.md#extension)
|
||||
Any extensions specified on the Cadl operation with the [(OpenAPI) `@extension` decorator](./reference/decorators.md#OpenAPI.extension)
|
||||
are included in the emitted OpenAPI operation.
|
||||
|
||||
## Models and enums
|
||||
|
|
@ -168,7 +168,7 @@ For an array type:
|
|||
| `@minItems(value)` | built-in | `minItems: value` | |
|
||||
| `@maxItems(value)` | built-in | `maxItems: value` | |
|
||||
|
||||
The OpenAPI emitter provides an [`@useRef` decorator](./decorators.md#useref) which will replace the Cadl model type in emitter output
|
||||
The OpenAPI emitter provides an [`@useRef` decorator](./reference/decorators.md#@OpenAPI.useref) which will replace the Cadl model type in emitter output
|
||||
with a reference to a pre-existing named OpenAPI schema. This can be useful for "common" schemas.
|
||||
|
||||
Example:
|
||||
|
|
@ -255,12 +255,12 @@ union GoodBreed {
|
|||
The OpenAPI emitter represents either form of union with an `anyOf` with an element for each option of the union.
|
||||
The OpenAPI emitter ignores the "names" for variants in named unions.
|
||||
|
||||
The OpenAPI emitter also defines the[`@oneOf` decorator](./decorators.md#oneof) which can be specified on a `union` statement to indicate
|
||||
The OpenAPI emitter also defines the[`@oneOf` decorator](./reference/decorators.md#OpenAPI.oneof) which can be specified on a `union` statement to indicate
|
||||
that a union should be emitted as a `oneOf` rather than `anyOf`.
|
||||
|
||||
## Security Definitions
|
||||
|
||||
The OpenAPI emitter takes the [(http) `@useAuth` decorator](../rest/decorators.md#useauth)
|
||||
The OpenAPI emitter takes the [(http) `@useAuth` decorator](../rest/reference/decorators.md#@Cadl.Http.useauth)
|
||||
|
||||
### Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
title: "Decorators"
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## OpenAPI
|
||||
|
||||
### `@operationId` {#@OpenAPI.operationId}
|
||||
|
||||
Specify the OpenAPI `operationId` property for this operation.
|
||||
|
||||
```cadl
|
||||
dec OpenAPI.operationId(target: Cadl.Reflection.Operation, operationId: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ----------- | -------------------- | ------------------- |
|
||||
| operationId | `scalar Cadl.string` | Operation id value. |
|
||||
|
||||
### `@extension` {#@OpenAPI.extension}
|
||||
|
||||
Attach some custom data to the OpenAPI element generated from this type.
|
||||
|
||||
```cadl
|
||||
dec OpenAPI.extension(target: unknown, key: Cadl.string, value: unknown)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`(intrinsic) unknown`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ----- | --------------------- | ----------------------------------- |
|
||||
| key | `scalar Cadl.string` | Extension key. Must start with `x-` |
|
||||
| value | `(intrinsic) unknown` | Extension value. |
|
||||
|
||||
### `@defaultResponse` {#@OpenAPI.defaultResponse}
|
||||
|
||||
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.
|
||||
|
||||
```cadl
|
||||
dec OpenAPI.defaultResponse(target: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`model Cadl.object`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@defaultResponse
|
||||
model PetStoreResponse is object;
|
||||
|
||||
op listPets(): Pet[] | PetStoreResponse;
|
||||
```
|
||||
|
||||
### `@externalDocs` {#@OpenAPI.externalDocs}
|
||||
|
||||
Specify the OpenAPI `externalDocs` property for this type.
|
||||
|
||||
```cadl
|
||||
dec OpenAPI.externalDocs(target: unknown, url: Cadl.string, description?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`(intrinsic) unknown`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ----------- | -------------------- | ----------------------- |
|
||||
| url | `scalar Cadl.string` | Url to the docs |
|
||||
| description | `scalar Cadl.string` | Description of the docs |
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Index
|
||||
sidebar_position: 0
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
## OpenAPI
|
||||
|
||||
### Decorators
|
||||
|
||||
- [`@operationId`](./decorators.md#@OpenAPI.operationId)
|
||||
- [`@extension`](./decorators.md#@OpenAPI.extension)
|
||||
- [`@defaultResponse`](./decorators.md#@OpenAPI.defaultResponse)
|
||||
- [`@externalDocs`](./decorators.md#@OpenAPI.externalDocs)
|
||||
|
|
@ -1,395 +0,0 @@
|
|||
---
|
||||
title: Decorators
|
||||
---
|
||||
|
||||
# Http And Rest Decorators
|
||||
|
||||
- [Http decorators](#http-decorators) (`Cadl.Http` namespace)
|
||||
|
||||
- [Verb decorators](#http-verb-decorators)
|
||||
- [@get](#get)
|
||||
- [@put](#put)
|
||||
- [@post](#post)
|
||||
- [@patch](#patch)
|
||||
- [@delete](#delete)
|
||||
- [@head](#head)
|
||||
- [Routing](#routing)
|
||||
- [@route](#route)
|
||||
- [Data types](#data-types)
|
||||
- [@header](#header)
|
||||
- [@query](#query)
|
||||
- [@path](#path)
|
||||
- [@body](#body)
|
||||
- [@statusCode](#statuscode)
|
||||
- [Service decorators](#service-decorators)
|
||||
- [@server](#server)
|
||||
- [@useAuth](#useauth)
|
||||
- [Metadata decorators](#metadata-decorators)
|
||||
- [@includeInapplicableMetadataInPayload](#includeinapplicablemetadatainpayload)
|
||||
|
||||
- [Rest decorators](#rest-decorators) (`Cadl.Rest` namespace)
|
||||
- [Routing](#rest-routing)
|
||||
- [@autoRoute](#autoroute)
|
||||
- [@segment](#segment)
|
||||
- [@segmentOf](#segmentof)
|
||||
- [@segmentSeparator](#segmentseparator)
|
||||
- [@actionSeparator](#actionseparator)
|
||||
- [Resource](#resource-decorators)
|
||||
- [@resource](#resource)
|
||||
- [@readsResource](#readsresource)
|
||||
- [@createsResource](#createsresource)
|
||||
- [@createsOrReplacesResource](#createsorreplacesresource)
|
||||
- [@createsOrUpdatesResource](#createsorupdatesresource)
|
||||
- [@updatesResource](#updatesresource)
|
||||
- [@deletesResource](#deletesresource)
|
||||
- [@listsResource](#listsresource)
|
||||
- [@parentResource](#parentresource)
|
||||
|
||||
## Http decorators
|
||||
|
||||
Http decorators are available in the `Cadl.Http` namespace.
|
||||
|
||||
### Http verb decorators
|
||||
|
||||
#### `@get`
|
||||
|
||||
Specify the http verb for the target operation to be `GET`.
|
||||
|
||||
```cadl
|
||||
@get op read(): Pet;
|
||||
```
|
||||
|
||||
#### `@put`
|
||||
|
||||
Specify the http verb for the target operation to be `PUT`.
|
||||
|
||||
```cadl
|
||||
@put op write(pet: Pet): void;
|
||||
```
|
||||
|
||||
#### `@post`
|
||||
|
||||
Specify the http verb for the target operation to be `POST`.
|
||||
|
||||
```cadl
|
||||
@post op add(pet: Pet): void;
|
||||
```
|
||||
|
||||
#### `@patch`
|
||||
|
||||
Specify the http verb for the target operation to be `PATCH`.
|
||||
|
||||
```cadl
|
||||
@patch op patch(pet: Pet): void;
|
||||
```
|
||||
|
||||
#### `@delete`
|
||||
|
||||
Specify the http verb for the target operation to be `DELETE`.
|
||||
|
||||
```cadl
|
||||
@delete op delete(pet: Pet): void;
|
||||
```
|
||||
|
||||
#### `@head`
|
||||
|
||||
Specify the http verb for the target operation to be `HEAD`.
|
||||
|
||||
```cadl
|
||||
@head op getInfo(): HeadInfo;
|
||||
```
|
||||
|
||||
### Routing
|
||||
|
||||
#### `@route`
|
||||
|
||||
Specify the route of an operation
|
||||
|
||||
```cadl
|
||||
@route("/pets") op list(): Pet[];
|
||||
```
|
||||
|
||||
Path parameter can be defined using `{}` with the name matching the path property. Using the [`@path`](#path) decorator on the property is optional.
|
||||
|
||||
```cadl
|
||||
@route("/pets/{petId}") op getPet(petId: string): Pet;
|
||||
```
|
||||
|
||||
### Data types
|
||||
|
||||
#### `@header`
|
||||
|
||||
Specify a model property is to be sent or is received as an header
|
||||
|
||||
```ts
|
||||
dec header(target: ModelProperty, headerName?: string);
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `headerName` _Optional_ Specify the name of the header in the http request/response.
|
||||
|
||||
**Example**
|
||||
|
||||
```cadl
|
||||
op configure(@header fileType: string): void;
|
||||
```
|
||||
|
||||
#### `@query`
|
||||
|
||||
Specify a model property is to be sent as a query parameter
|
||||
|
||||
```ts
|
||||
dec query(target: ModelProperty, queryName?: string);
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `queryName` _Optional_ Specify the name of the query in the http request.
|
||||
|
||||
**Example**
|
||||
|
||||
```cadl
|
||||
op list(@query filter: string): Pet[];
|
||||
```
|
||||
|
||||
#### `@path`
|
||||
|
||||
Specify explicitly that a model property is to be interpolated as a path parameter.
|
||||
By default if an operation paramater has the same name as the path parameter defined in [`@route`](#route) it will be inferred as a path parameter.
|
||||
|
||||
```cadl
|
||||
@route("/store/{storeId}/pets") op list(@path storeId: string): Pet[];
|
||||
```
|
||||
|
||||
#### `@body`
|
||||
|
||||
Explicitly specify that this property is to be set as the body
|
||||
|
||||
```cadl
|
||||
op add(@body pet: Pet): void;
|
||||
```
|
||||
|
||||
#### `@statusCode`
|
||||
|
||||
Specify the status code for this response
|
||||
|
||||
```cadl
|
||||
op read(): {
|
||||
@statusCode _: 200;
|
||||
...Pet;
|
||||
} | {
|
||||
@statusCode _: 404;
|
||||
};
|
||||
```
|
||||
|
||||
### Service decorators
|
||||
|
||||
#### `@server`
|
||||
|
||||
Specify the endpoint for the service.
|
||||
|
||||
Here's an example that uses these to define a Pet Store service:
|
||||
|
||||
```cadl
|
||||
@service
|
||||
@server("https://example.com", "Single server endpoint")
|
||||
namespace PetStore;
|
||||
```
|
||||
|
||||
The `@server` decorator can take a third parameter with parameters as necessary:
|
||||
|
||||
```cadl
|
||||
@server("https://{region}.foo.com", "Regional endpoint", {
|
||||
@doc("Region name")
|
||||
region?: string = "westus",
|
||||
})
|
||||
```
|
||||
|
||||
#### `@useAuth`
|
||||
|
||||
Specify the authentication for the service with the `@useAuth` decorator on the service namespace.
|
||||
|
||||
The decorator accepts a single security scheme, a tuple of security schemes (both are used),
|
||||
a union of security schemes (either can be used), or a union of tuples of security schemes.
|
||||
|
||||
A simple example:
|
||||
|
||||
```cadl
|
||||
@service
|
||||
@useAuth(BasicAuth)
|
||||
namespace PetStore;
|
||||
```
|
||||
|
||||
See the [documentation in the Http library][authentication] for full details.
|
||||
|
||||
[authentication]: https://github.com/microsoft/cadl/blob/main/docs/standard-library/rest/authentication.md
|
||||
|
||||
### Metadata decorators
|
||||
|
||||
#### `@includeInapplicableMetadataInPayload`
|
||||
|
||||
Specify if inapplicable [metadata](./operations.md#metadata) should be included in the payload for the given entity.
|
||||
|
||||
This is true by default unless changed by this decorator.
|
||||
|
||||
Can be applied to namespaces, models, and model properties. If applied to a model or namespace, applies recursively to child models,
|
||||
namespaces, and model properties unless overridden by applying this decorator to a child.
|
||||
|
||||
## Rest decorators
|
||||
|
||||
Rest decorators are available in the `Cadl.Http` namespace.
|
||||
|
||||
## Rest routing
|
||||
|
||||
#### `@autoRoute`
|
||||
|
||||
Namespace, interface or operation should resolve their route automatically. To be used with resource types where the route segments area defined on the models.
|
||||
|
||||
```cadl
|
||||
@autoRoute
|
||||
interface Pets {
|
||||
get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
|
||||
}
|
||||
```
|
||||
|
||||
#### `@segment`
|
||||
|
||||
Specify the segment for the resource. To be used with [@autoRoute](#autoroute)
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@segment(<StringLiteral>)
|
||||
```
|
||||
|
||||
`@segment` defines the preceding path segment for a @path parameter in auto-generated routes. The first argument should be a string that will be inserted into the operation route before the path parameter's name field.
|
||||
|
||||
```cadl
|
||||
@autoRoute
|
||||
interface Pets {
|
||||
get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
|
||||
}
|
||||
```
|
||||
|
||||
#### `@segmentOf`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@segment(<StringLiteral>)
|
||||
```
|
||||
|
||||
`@segmentOf` returns the URL segment of a given model if it has `@segment` and `@key` decorator.
|
||||
|
||||
#### `@segmentSeparator`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@segmentSeparator(<StringLiteral>)
|
||||
```
|
||||
|
||||
`@segmentSeparator` defines the separator string that is inserted between the target's `@segment` and the preceding route path in auto-generated routes.
|
||||
The first argument should be a string that will be inserted into the operation route before the target's `@segment` value. Can be a string of any length. Defaults to `/`.
|
||||
|
||||
#### `@actionSeparator`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@actionSeparator(<StringLiteral>)
|
||||
```
|
||||
|
||||
`@actionSeparator` defines the separator string that is inserted before the action name in auto-generated routes for actions.
|
||||
|
||||
### Resource decorators
|
||||
|
||||
#### `@resource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@resource(<StringLiteral>)
|
||||
```
|
||||
|
||||
This decorator is to used to mark a model as a resource type with a name for the type's collection.
|
||||
|
||||
#### `@readsResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@readsResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the Read operation for a particular resource.
|
||||
|
||||
#### `@createsResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@createsResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the Create operation for a particular resource.
|
||||
|
||||
#### `@createsOrReplacesResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@createsOrReplacesResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the CreatesOrReplace operation for a particular resource.
|
||||
|
||||
#### `@createsOrUpdatesResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@createsOrUpdatesResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the CreatesOrUpdate operation for a particular resource.
|
||||
|
||||
#### `@updatesResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@updatesResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the Update operation for a particular resource.
|
||||
|
||||
#### `@deletesResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@deletesResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the Delete operation for a particular resource.
|
||||
|
||||
#### `@listsResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@listsResource(<Model>)
|
||||
```
|
||||
|
||||
This decorator is to used to signal the operation that is the List operation for a particular resource.
|
||||
|
||||
#### `@parentResource`
|
||||
|
||||
Syntax:
|
||||
|
||||
```cadl
|
||||
@parentResource(parentModelType<Model>)
|
||||
```
|
||||
|
||||
`@parentResource` marks a model property with a reference to its parent resource type. The first argument should be a reference to a model type which will be treated as the parent type of the target model type. This will cause the `@key` properties of all parent types of the target type to show up in operations of the `Resource*<T>` interfaces defined in this library. |
|
||||
|
|
@ -6,7 +6,7 @@ title: Operations
|
|||
|
||||
## Operation verb
|
||||
|
||||
You can use one of the [verb decorators](./decorators.md#verb-decorators): `@get`, `@put`, etc.
|
||||
You can use one of the [verb decorators](./reference/decorators.md): `@get`, `@put`, etc.
|
||||
|
||||
## Route
|
||||
|
||||
|
|
@ -335,7 +335,7 @@ Metadata is determined to be applicable or inapplicable based on the context tha
|
|||
|
||||
Additionally metadata that appears in an array element type always inapplicable.
|
||||
|
||||
When metadata is deemed "inapplicable", for example, if a `@path` property is seen in a response, it becomes part of the payload instead unless the [@includeInapplicableMetadataInPayload](./decorators.md#includeinapplicablemetadatainpayload) decorator is used and given a value of `false`.
|
||||
When metadata is deemed "inapplicable", for example, if a `@path` property is seen in a response, it becomes part of the payload instead unless the [@includeInapplicableMetadataInPayload](./reference/decorators.md#@Cadl.Rest.includeinapplicablemetadatainpayload) decorator is used and given a value of `false`.
|
||||
|
||||
The handling of metadata applicability furthers the goal of keeping a single logical model in Cadl. For example, this defines a logical `User` entity that has a name, ID and password, but further annotates that the ID is sent in the HTTP path and the HTTP body in responses. Also, using automatically visibility as before, we further indicate that the password is only present in create requests.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,10 @@ npm install @cadl-lang/rest
|
|||
|
||||
## Details
|
||||
|
||||
- [Decorators references](./decorators.md)
|
||||
- [References](./reference/index.md)
|
||||
- [Decorators](./reference/decorators.md)
|
||||
- [Data types](./reference/data-types.md)
|
||||
- [Interface and operations](./reference/interfaces.md)
|
||||
- [Authentication](./authentication.md)
|
||||
|
||||
## Cheat sheet
|
||||
|
|
|
|||
|
|
@ -0,0 +1,785 @@
|
|||
---
|
||||
title: "Data types"
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Data types
|
||||
|
||||
## Cadl.Http
|
||||
|
||||
### `Response` {#Cadl.Http.Response}
|
||||
|
||||
```cadl
|
||||
model Response<Status>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ------ | ----------- |
|
||||
| Status | |
|
||||
|
||||
### `Body` {#Cadl.Http.Body}
|
||||
|
||||
Defines a model with a single property of the given type, marked with `@body`.
|
||||
|
||||
This can be useful in situations where you cannot use a bare T as the body
|
||||
and it is awkward to add a property.
|
||||
|
||||
```cadl
|
||||
model Body<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `LocationHeader` {#Cadl.Http.LocationHeader}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.LocationHeader
|
||||
```
|
||||
|
||||
### `OkResponse` {#Cadl.Http.OkResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.OkResponse
|
||||
```
|
||||
|
||||
### `CreatedResponse` {#Cadl.Http.CreatedResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.CreatedResponse
|
||||
```
|
||||
|
||||
### `AcceptedResponse` {#Cadl.Http.AcceptedResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.AcceptedResponse
|
||||
```
|
||||
|
||||
### `NoContentResponse` {#Cadl.Http.NoContentResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.NoContentResponse
|
||||
```
|
||||
|
||||
### `MovedResponse` {#Cadl.Http.MovedResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.MovedResponse
|
||||
```
|
||||
|
||||
### `NotModifiedResponse` {#Cadl.Http.NotModifiedResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.NotModifiedResponse
|
||||
```
|
||||
|
||||
### `BadRequestResponse` {#Cadl.Http.BadRequestResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.BadRequestResponse
|
||||
```
|
||||
|
||||
### `UnauthorizedResponse` {#Cadl.Http.UnauthorizedResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.UnauthorizedResponse
|
||||
```
|
||||
|
||||
### `ForbiddenResponse` {#Cadl.Http.ForbiddenResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.ForbiddenResponse
|
||||
```
|
||||
|
||||
### `NotFoundResponse` {#Cadl.Http.NotFoundResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.NotFoundResponse
|
||||
```
|
||||
|
||||
### `ConflictResponse` {#Cadl.Http.ConflictResponse}
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.ConflictResponse
|
||||
```
|
||||
|
||||
### `PlainData` {#Cadl.Http.PlainData}
|
||||
|
||||
Produces a new model with the same properties as T, but with `@query`,
|
||||
`@header`, `@body`, and `@path` decorators removed from all properties.
|
||||
|
||||
```cadl
|
||||
model PlainData<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `BasicAuth` {#Cadl.Http.BasicAuth}
|
||||
|
||||
Basic authentication is a simple authentication scheme built into the HTTP protocol.
|
||||
The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
|
||||
For example, to authorize as demo / `p@55w0rd` the client would send
|
||||
|
||||
```
|
||||
Authorization: Basic ZGVtbzpwQDU1dzByZA==
|
||||
```
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.BasicAuth
|
||||
```
|
||||
|
||||
### `BearerAuth` {#Cadl.Http.BearerAuth}
|
||||
|
||||
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
|
||||
The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request.
|
||||
The client must send this token in the Authorization header when making requests to protected resources:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.BearerAuth
|
||||
```
|
||||
|
||||
### `ApiKeyAuth` {#Cadl.Http.ApiKeyAuth}
|
||||
|
||||
An API key is a token that a client provides when making API calls. The key can be sent in the query string:
|
||||
|
||||
```
|
||||
GET /something?api_key=abcdef12345
|
||||
```
|
||||
|
||||
or as a request header
|
||||
|
||||
```
|
||||
GET /something HTTP/1.1
|
||||
X-API-Key: abcdef12345
|
||||
```
|
||||
|
||||
or as a cookie
|
||||
|
||||
```
|
||||
GET /something HTTP/1.1
|
||||
Cookie: X-API-KEY=abcdef12345
|
||||
```
|
||||
|
||||
```cadl
|
||||
model ApiKeyAuth<TLocation, TName>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TLocation | |
|
||||
| TName | |
|
||||
|
||||
### `OAuth2Auth` {#Cadl.Http.OAuth2Auth}
|
||||
|
||||
OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
|
||||
OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials.
|
||||
For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
|
||||
For more information about OAuth 2.0, see oauth.net and RFC 6749.
|
||||
|
||||
```cadl
|
||||
model OAuth2Auth<TFlows>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ------ | ----------- |
|
||||
| TFlows | |
|
||||
|
||||
### `AuthorizationCodeFlow` {#Cadl.Http.AuthorizationCodeFlow}
|
||||
|
||||
Authorization Code flow
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.AuthorizationCodeFlow
|
||||
```
|
||||
|
||||
### `ImplicitFlow` {#Cadl.Http.ImplicitFlow}
|
||||
|
||||
Implicit flow
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.ImplicitFlow
|
||||
```
|
||||
|
||||
### `PasswordFlow` {#Cadl.Http.PasswordFlow}
|
||||
|
||||
Resource Owner Password flow
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.PasswordFlow
|
||||
```
|
||||
|
||||
### `ClientCredentialsFlow` {#Cadl.Http.ClientCredentialsFlow}
|
||||
|
||||
Client credentials flow
|
||||
|
||||
```cadl
|
||||
model Cadl.Http.ClientCredentialsFlow
|
||||
```
|
||||
|
||||
### `AuthType` {#Cadl.Http.AuthType}
|
||||
|
||||
Authentication type
|
||||
|
||||
```cadl
|
||||
enum Cadl.Http.AuthType
|
||||
```
|
||||
|
||||
### `ApiKeyLocation` {#Cadl.Http.ApiKeyLocation}
|
||||
|
||||
Describes the location of the API key
|
||||
|
||||
```cadl
|
||||
enum Cadl.Http.ApiKeyLocation
|
||||
```
|
||||
|
||||
### `OAuth2FlowType` {#Cadl.Http.OAuth2FlowType}
|
||||
|
||||
Describes the OAuth2 flow type
|
||||
|
||||
```cadl
|
||||
enum Cadl.Http.OAuth2FlowType
|
||||
```
|
||||
|
||||
## Cadl.Rest.Resource
|
||||
|
||||
### `ResourceError` {#Cadl.Rest.Resource.ResourceError}
|
||||
|
||||
The default error response for resource operations.
|
||||
|
||||
```cadl
|
||||
model Cadl.Rest.Resource.ResourceError
|
||||
```
|
||||
|
||||
### `KeysOf` {#Cadl.Rest.Resource.KeysOf}
|
||||
|
||||
```cadl
|
||||
model KeysOf<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ParentKeysOf` {#Cadl.Rest.Resource.ParentKeysOf}
|
||||
|
||||
```cadl
|
||||
model ParentKeysOf<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceParameters` {#Cadl.Rest.Resource.ResourceParameters}
|
||||
|
||||
```cadl
|
||||
model ResourceParameters<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCollectionParameters` {#Cadl.Rest.Resource.ResourceCollectionParameters}
|
||||
|
||||
```cadl
|
||||
model ResourceCollectionParameters<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceDeletedResponse` {#Cadl.Rest.Resource.ResourceDeletedResponse}
|
||||
|
||||
Resource deleted successfully.
|
||||
|
||||
```cadl
|
||||
model Cadl.Rest.Resource.ResourceDeletedResponse
|
||||
```
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `ResourceCreateOrUpdateModel` {#Cadl.Rest.Resource.ResourceCreateOrUpdateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateOrUpdateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreateModel` {#Cadl.Rest.Resource.ResourceCreateModel}
|
||||
|
||||
```cadl
|
||||
model ResourceCreateModel<TResource>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
|
||||
### `ResourceCreatedResponse` {#Cadl.Rest.Resource.ResourceCreatedResponse}
|
||||
|
||||
```cadl
|
||||
model ResourceCreatedResponse<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
||||
### `CollectionWithNextLink` {#Cadl.Rest.Resource.CollectionWithNextLink}
|
||||
|
||||
Structure for a paging response using `value` and `nextLink` to represent pagination.
|
||||
This only provides the model structure and not actual pagination support.
|
||||
See https://github.com/microsoft/cadl/issues/705 for general paging support.
|
||||
|
||||
```cadl
|
||||
model CollectionWithNextLink<T>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| T | |
|
||||
|
|
@ -0,0 +1,584 @@
|
|||
---
|
||||
title: "Decorators"
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Decorators
|
||||
|
||||
## Cadl.Http
|
||||
|
||||
### `@statusCode` {#@Cadl.Http.statusCode}
|
||||
|
||||
Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.statusCode(target: Cadl.Reflection.ModelProperty)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`ModelProperty`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
op read(): {@statusCode: 200, @body pet: Pet}
|
||||
op create(): {@statusCode: 201 | 202}
|
||||
```
|
||||
|
||||
### `@body` {#@Cadl.Http.body}
|
||||
|
||||
Explicitly specify that this property is to be set as the body
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.body(target: Cadl.Reflection.ModelProperty)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`ModelProperty`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
op upload(@body image: bytes): void;
|
||||
op download(): {@body image: bytes};
|
||||
```
|
||||
|
||||
### `@header` {#@Cadl.Http.header}
|
||||
|
||||
Specify this property is to be sent or received as an http header.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.header(target: Cadl.Reflection.ModelProperty, headerName?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`ModelProperty`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---------- | -------------------- | ------------------------------------------------ |
|
||||
| headerName | `scalar Cadl.string` | Optional name of the header when sent over http. |
|
||||
|
||||
### `@query` {#@Cadl.Http.query}
|
||||
|
||||
Specify this property is to be sent as a query parameter.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.query(target: Cadl.Reflection.ModelProperty, queryKey?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`ModelProperty`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| -------- | -------------------- | ---------------------------------------------------- |
|
||||
| queryKey | `scalar Cadl.string` | Optional name of the query when included in the url. |
|
||||
|
||||
### `@path` {#@Cadl.Http.path}
|
||||
|
||||
Explicitly specify that this property is to be interpolated as a path parameter.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.path(target: Cadl.Reflection.ModelProperty, paramName?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`ModelProperty`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------- | -------------------- | --------------------------------------------------- |
|
||||
| paramName | `scalar Cadl.string` | Optional name of the parmaeter in the url template. |
|
||||
|
||||
### `@get` {#@Cadl.Http.get}
|
||||
|
||||
Specify the http verb for the target operation to be `GET`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.get(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@get op read(): string
|
||||
```
|
||||
|
||||
### `@put` {#@Cadl.Http.put}
|
||||
|
||||
Specify the http verb for the target operation to be `PUT`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.put(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@put op set(pet: Pet): void
|
||||
```
|
||||
|
||||
### `@post` {#@Cadl.Http.post}
|
||||
|
||||
Specify the http verb for the target operation to be `POST`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.post(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@post op create(pet: Pet): void
|
||||
```
|
||||
|
||||
### `@patch` {#@Cadl.Http.patch}
|
||||
|
||||
Specify the http verb for the target operation to be `PATCH`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.patch(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@patch op update(pet: Pet): void
|
||||
```
|
||||
|
||||
### `@delete` {#@Cadl.Http.delete}
|
||||
|
||||
Specify the http verb for the target operation to be `DELETE`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.delete(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@delete op set(petId: string): void
|
||||
```
|
||||
|
||||
### `@head` {#@Cadl.Http.head}
|
||||
|
||||
Specify the http verb for the target operation to be `HEAD`.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.head(target: Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@head op ping(petId: string): void
|
||||
```
|
||||
|
||||
### `@server` {#@Cadl.Http.server}
|
||||
|
||||
Specify the endpoint for this service.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.server(target: Cadl.Reflection.Namespace, url: Cadl.string, description: Cadl.string, parameters?: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Namespace`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ----------- | -------------------- | ------------------------------------------------------- |
|
||||
| url | `scalar Cadl.string` | Description of the endpoint |
|
||||
| description | `scalar Cadl.string` | |
|
||||
| parameters | `model Cadl.object` | Optional set of parameters used to interpolate the url. |
|
||||
|
||||
### `@useAuth` {#@Cadl.Http.useAuth}
|
||||
|
||||
Specify this service authentication. See the [documentation in the Http library][https://microsoft.github.io/cadl/standard-library/rest/authentication] for full details.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.useAuth(target: Cadl.Reflection.Namespace, auth: Cadl.object | Cadl.Reflection.Union | Cadl.object[])
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Namespace`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ------------------ | --------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| auth | `union Cadl.object | Cadl.Reflection.Union | Cadl.object[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple(Must use all authentication together) |
|
||||
|
||||
### `@includeInapplicableMetadataInPayload` {#@Cadl.Http.includeInapplicableMetadataInPayload}
|
||||
|
||||
Specify if inapplicable metadata should be included in the payload for the given entity.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Http.includeInapplicableMetadataInPayload(target: unknown, value: Cadl.boolean)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`(intrinsic) unknown`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ----- | --------------------- | ----------- |
|
||||
| value | `scalar Cadl.boolean` | |
|
||||
|
||||
## Cadl.Rest
|
||||
|
||||
### `@autoRoute` {#@Cadl.Rest.autoRoute}
|
||||
|
||||
This namespace, interface or operation should resolve its route automatically. To be used with resource types where the route segments area defined on the models.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.autoRoute(target: Cadl.Reflection.Namespace | Cadl.Reflection.Interface | Cadl.Reflection.Operation)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`union Cadl.Reflection.Namespace | Cadl.Reflection.Interface | Cadl.Reflection.Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
|
||||
#### Examples
|
||||
|
||||
```cadl
|
||||
@autoRoute
|
||||
interface Pets {
|
||||
get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
|
||||
}
|
||||
```
|
||||
|
||||
### `@segment` {#@Cadl.Rest.segment}
|
||||
|
||||
Defines the preceding path segment for a
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.segment(target: Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation, name: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`union Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | -------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| name | `scalar Cadl.string` | Segment that will be inserted into the operation route before the path parameter's name field. |
|
||||
|
||||
### `@segmentOf` {#@Cadl.Rest.segmentOf}
|
||||
|
||||
Returns the URL segment of a given model if it has `@segment` and `@key` decorator.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.segmentOf(target: Cadl.Reflection.Operation, type: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ------------------- | ----------- |
|
||||
| type | `model Cadl.object` | |
|
||||
|
||||
### `@actionSeparator` {#@Cadl.Rest.actionSeparator}
|
||||
|
||||
Defines the separator string that is inserted before the action name in auto-generated routes for actions.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.actionSeparator(target: Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation, seperator: / | : | /:)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`union Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------- | -------- | ----------- | --- | ---------------------------------------------------------------- |
|
||||
| seperator | `union / | : | /:` | Seperator seperating the action segment from the rest of the url |
|
||||
|
||||
### `@segmentSeparator` {#@Cadl.Rest.segmentSeparator}
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.segmentSeparator(target: Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation, seperator: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`union Cadl.object | Cadl.Reflection.ModelProperty | Cadl.Reflection.Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------- | -------------------- | ----------- |
|
||||
| seperator | `scalar Cadl.string` | |
|
||||
|
||||
### `@resource` {#@Cadl.Rest.resource}
|
||||
|
||||
Mark this model as a resource type with a name.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.resource(target: Cadl.object, collectionName: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`model Cadl.object`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| -------------- | -------------------- | ---------------------- |
|
||||
| collectionName | `scalar Cadl.string` | type's collection name |
|
||||
|
||||
### `@readsResource` {#@Cadl.Rest.readsResource}
|
||||
|
||||
Specify that this is a Read operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.readsResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@createsResource` {#@Cadl.Rest.createsResource}
|
||||
|
||||
Specify that this is a Create operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.createsResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@createsOrReplacesResource` {#@Cadl.Rest.createsOrReplacesResource}
|
||||
|
||||
Specify that this is a CreateOrReplace operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.createsOrReplacesResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@createsOrUpdatesResource` {#@Cadl.Rest.createsOrUpdatesResource}
|
||||
|
||||
Specify that this is a CreatesOrUpdate operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.createsOrUpdatesResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@updatesResource` {#@Cadl.Rest.updatesResource}
|
||||
|
||||
Specify that this is a Update operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.updatesResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@deletesResource` {#@Cadl.Rest.deletesResource}
|
||||
|
||||
Specify that this is a Delete operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.deletesResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@listsResource` {#@Cadl.Rest.listsResource}
|
||||
|
||||
Specify that this is a List operation for a given resource.
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.listsResource(target: Cadl.Reflection.Operation, resourceType: Cadl.object)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
|
||||
### `@action` {#@Cadl.Rest.action}
|
||||
|
||||
Specify this operation is an action. (Scopped to a resource item /pets/{petId}/my-action)
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.action(target: Cadl.Reflection.Operation, name?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | -------------------- | ----------- |
|
||||
| name | `scalar Cadl.string` | |
|
||||
|
||||
### `@collectionAction` {#@Cadl.Rest.collectionAction}
|
||||
|
||||
Specify this operation is a collection action. (Scopped to a resource, /pets/my-action)
|
||||
|
||||
```cadl
|
||||
dec Cadl.Rest.collectionAction(target: Cadl.Reflection.Operation, resourceType: Cadl.object, name?: Cadl.string)
|
||||
```
|
||||
|
||||
#### Target
|
||||
|
||||
`Operation`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | -------------------- | ----------- |
|
||||
| resourceType | `model Cadl.object` | |
|
||||
| name | `scalar Cadl.string` | |
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
title: Index
|
||||
sidebar_position: 0
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
## Cadl.Http
|
||||
|
||||
### Decorators
|
||||
|
||||
- [`@statusCode`](./decorators.md#@Cadl.Http.statusCode)
|
||||
- [`@body`](./decorators.md#@Cadl.Http.body)
|
||||
- [`@header`](./decorators.md#@Cadl.Http.header)
|
||||
- [`@query`](./decorators.md#@Cadl.Http.query)
|
||||
- [`@path`](./decorators.md#@Cadl.Http.path)
|
||||
- [`@get`](./decorators.md#@Cadl.Http.get)
|
||||
- [`@put`](./decorators.md#@Cadl.Http.put)
|
||||
- [`@post`](./decorators.md#@Cadl.Http.post)
|
||||
- [`@patch`](./decorators.md#@Cadl.Http.patch)
|
||||
- [`@delete`](./decorators.md#@Cadl.Http.delete)
|
||||
- [`@head`](./decorators.md#@Cadl.Http.head)
|
||||
- [`@server`](./decorators.md#@Cadl.Http.server)
|
||||
- [`@useAuth`](./decorators.md#@Cadl.Http.useAuth)
|
||||
- [`@includeInapplicableMetadataInPayload`](./decorators.md#@Cadl.Http.includeInapplicableMetadataInPayload)
|
||||
|
||||
### Models
|
||||
|
||||
- [`Response`](./data-types.md#Cadl.Http.Response)
|
||||
- [`Body`](./data-types.md#Cadl.Http.Body)
|
||||
- [`LocationHeader`](./data-types.md#Cadl.Http.LocationHeader)
|
||||
- [`OkResponse`](./data-types.md#Cadl.Http.OkResponse)
|
||||
- [`CreatedResponse`](./data-types.md#Cadl.Http.CreatedResponse)
|
||||
- [`AcceptedResponse`](./data-types.md#Cadl.Http.AcceptedResponse)
|
||||
- [`NoContentResponse`](./data-types.md#Cadl.Http.NoContentResponse)
|
||||
- [`MovedResponse`](./data-types.md#Cadl.Http.MovedResponse)
|
||||
- [`NotModifiedResponse`](./data-types.md#Cadl.Http.NotModifiedResponse)
|
||||
- [`BadRequestResponse`](./data-types.md#Cadl.Http.BadRequestResponse)
|
||||
- [`UnauthorizedResponse`](./data-types.md#Cadl.Http.UnauthorizedResponse)
|
||||
- [`ForbiddenResponse`](./data-types.md#Cadl.Http.ForbiddenResponse)
|
||||
- [`NotFoundResponse`](./data-types.md#Cadl.Http.NotFoundResponse)
|
||||
- [`ConflictResponse`](./data-types.md#Cadl.Http.ConflictResponse)
|
||||
- [`PlainData`](./data-types.md#Cadl.Http.PlainData)
|
||||
- [`BasicAuth`](./data-types.md#Cadl.Http.BasicAuth)
|
||||
- [`BearerAuth`](./data-types.md#Cadl.Http.BearerAuth)
|
||||
- [`ApiKeyAuth`](./data-types.md#Cadl.Http.ApiKeyAuth)
|
||||
- [`OAuth2Auth`](./data-types.md#Cadl.Http.OAuth2Auth)
|
||||
- [`AuthorizationCodeFlow`](./data-types.md#Cadl.Http.AuthorizationCodeFlow)
|
||||
- [`ImplicitFlow`](./data-types.md#Cadl.Http.ImplicitFlow)
|
||||
- [`PasswordFlow`](./data-types.md#Cadl.Http.PasswordFlow)
|
||||
- [`ClientCredentialsFlow`](./data-types.md#Cadl.Http.ClientCredentialsFlow)
|
||||
|
||||
## Cadl.Rest
|
||||
|
||||
### Decorators
|
||||
|
||||
- [`@autoRoute`](./decorators.md#@Cadl.Rest.autoRoute)
|
||||
- [`@segment`](./decorators.md#@Cadl.Rest.segment)
|
||||
- [`@segmentOf`](./decorators.md#@Cadl.Rest.segmentOf)
|
||||
- [`@actionSeparator`](./decorators.md#@Cadl.Rest.actionSeparator)
|
||||
- [`@segmentSeparator`](./decorators.md#@Cadl.Rest.segmentSeparator)
|
||||
- [`@resource`](./decorators.md#@Cadl.Rest.resource)
|
||||
- [`@readsResource`](./decorators.md#@Cadl.Rest.readsResource)
|
||||
- [`@createsResource`](./decorators.md#@Cadl.Rest.createsResource)
|
||||
- [`@createsOrReplacesResource`](./decorators.md#@Cadl.Rest.createsOrReplacesResource)
|
||||
- [`@createsOrUpdatesResource`](./decorators.md#@Cadl.Rest.createsOrUpdatesResource)
|
||||
- [`@updatesResource`](./decorators.md#@Cadl.Rest.updatesResource)
|
||||
- [`@deletesResource`](./decorators.md#@Cadl.Rest.deletesResource)
|
||||
- [`@listsResource`](./decorators.md#@Cadl.Rest.listsResource)
|
||||
- [`@action`](./decorators.md#@Cadl.Rest.action)
|
||||
- [`@collectionAction`](./decorators.md#@Cadl.Rest.collectionAction)
|
||||
|
||||
## Cadl.Rest.Resource
|
||||
|
||||
### Interfaces
|
||||
|
||||
- [`ResourceRead`](./interfaces.md#Cadl.Rest.Resource.ResourceRead)
|
||||
- [`ResourceCreateOrReplace`](./interfaces.md#Cadl.Rest.Resource.ResourceCreateOrReplace)
|
||||
- [`ResourceCreateOrUpdate`](./interfaces.md#Cadl.Rest.Resource.ResourceCreateOrUpdate)
|
||||
- [`ResourceCreate`](./interfaces.md#Cadl.Rest.Resource.ResourceCreate)
|
||||
- [`ResourceUpdate`](./interfaces.md#Cadl.Rest.Resource.ResourceUpdate)
|
||||
- [`ResourceDelete`](./interfaces.md#Cadl.Rest.Resource.ResourceDelete)
|
||||
- [`ResourceList`](./interfaces.md#Cadl.Rest.Resource.ResourceList)
|
||||
- [`ResourceInstanceOperations`](./interfaces.md#Cadl.Rest.Resource.ResourceInstanceOperations)
|
||||
- [`ResourceCollectionOperations`](./interfaces.md#Cadl.Rest.Resource.ResourceCollectionOperations)
|
||||
- [`ResourceOperations`](./interfaces.md#Cadl.Rest.Resource.ResourceOperations)
|
||||
- [`SingletonResourceRead`](./interfaces.md#Cadl.Rest.Resource.SingletonResourceRead)
|
||||
- [`SingletonResourceUpdate`](./interfaces.md#Cadl.Rest.Resource.SingletonResourceUpdate)
|
||||
- [`SingletonResourceOperations`](./interfaces.md#Cadl.Rest.Resource.SingletonResourceOperations)
|
||||
- [`ExtensionResourceRead`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceRead)
|
||||
- [`ExtensionResourceCreateOrUpdate`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceCreateOrUpdate)
|
||||
- [`ExtensionResourceCreate`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceCreate)
|
||||
- [`ExtensionResourceUpdate`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceUpdate)
|
||||
- [`ExtensionResourceDelete`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceDelete)
|
||||
- [`ExtensionResourceList`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceList)
|
||||
- [`ExtensionResourceInstanceOperations`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceInstanceOperations)
|
||||
- [`ExtensionResourceCollectionOperations`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceCollectionOperations)
|
||||
- [`ExtensionResourceOperations`](./interfaces.md#Cadl.Rest.Resource.ExtensionResourceOperations)
|
||||
|
||||
### Models
|
||||
|
||||
- [`ResourceError`](./data-types.md#Cadl.Rest.Resource.ResourceError)
|
||||
- [`KeysOf`](./data-types.md#Cadl.Rest.Resource.KeysOf)
|
||||
- [`ParentKeysOf`](./data-types.md#Cadl.Rest.Resource.ParentKeysOf)
|
||||
- [`ResourceParameters`](./data-types.md#Cadl.Rest.Resource.ResourceParameters)
|
||||
- [`ResourceCollectionParameters`](./data-types.md#Cadl.Rest.Resource.ResourceCollectionParameters)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceDeletedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceDeletedResponse)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
- [`ResourceCreateOrUpdateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateOrUpdateModel)
|
||||
- [`ResourceCreateModel`](./data-types.md#Cadl.Rest.Resource.ResourceCreateModel)
|
||||
- [`ResourceCreatedResponse`](./data-types.md#Cadl.Rest.Resource.ResourceCreatedResponse)
|
||||
- [`CollectionWithNextLink`](./data-types.md#Cadl.Rest.Resource.CollectionWithNextLink)
|
||||
|
|
@ -0,0 +1,309 @@
|
|||
---
|
||||
title: "Interfaces and Operations"
|
||||
toc_min_heading_level: 2
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
# Interfaces and Operations
|
||||
|
||||
## Cadl.Rest.Resource
|
||||
|
||||
### `ResourceRead` {#Cadl.Rest.Resource.ResourceRead}
|
||||
|
||||
Represent the resource GET operation.
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceRead<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ------------------- |
|
||||
| TResource | The resource model. |
|
||||
| TError | The error response. |
|
||||
|
||||
### `ResourceCreateOrReplace` {#Cadl.Rest.Resource.ResourceCreateOrReplace}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceCreateOrReplace<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceCreateOrUpdate` {#Cadl.Rest.Resource.ResourceCreateOrUpdate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceCreateOrUpdate<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceCreate` {#Cadl.Rest.Resource.ResourceCreate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceCreate<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceUpdate` {#Cadl.Rest.Resource.ResourceUpdate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceUpdate<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceDelete` {#Cadl.Rest.Resource.ResourceDelete}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceDelete<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceList` {#Cadl.Rest.Resource.ResourceList}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceList<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceInstanceOperations` {#Cadl.Rest.Resource.ResourceInstanceOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceInstanceOperations<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceCollectionOperations` {#Cadl.Rest.Resource.ResourceCollectionOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceCollectionOperations<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ResourceOperations` {#Cadl.Rest.Resource.ResourceOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ResourceOperations<TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| --------- | ----------- |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `SingletonResourceRead` {#Cadl.Rest.Resource.SingletonResourceRead}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.SingletonResourceRead<TSingleton, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TSingleton | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `SingletonResourceUpdate` {#Cadl.Rest.Resource.SingletonResourceUpdate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.SingletonResourceUpdate<TSingleton, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TSingleton | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `SingletonResourceOperations` {#Cadl.Rest.Resource.SingletonResourceOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.SingletonResourceOperations<TSingleton, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TSingleton | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceRead` {#Cadl.Rest.Resource.ExtensionResourceRead}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceRead<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceCreateOrUpdate` {#Cadl.Rest.Resource.ExtensionResourceCreateOrUpdate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceCreateOrUpdate<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceCreate` {#Cadl.Rest.Resource.ExtensionResourceCreate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceCreate<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceUpdate` {#Cadl.Rest.Resource.ExtensionResourceUpdate}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceUpdate<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceDelete` {#Cadl.Rest.Resource.ExtensionResourceDelete}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceDelete<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceList` {#Cadl.Rest.Resource.ExtensionResourceList}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceList<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceInstanceOperations` {#Cadl.Rest.Resource.ExtensionResourceInstanceOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceInstanceOperations<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceCollectionOperations` {#Cadl.Rest.Resource.ExtensionResourceCollectionOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceCollectionOperations<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
||||
### `ExtensionResourceOperations` {#Cadl.Rest.Resource.ExtensionResourceOperations}
|
||||
|
||||
```cadl
|
||||
interface Cadl.Rest.Resource.ExtensionResourceOperations<TExtension, TResource, TError>
|
||||
```
|
||||
|
||||
#### Template Parameters
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| TExtension | |
|
||||
| TResource | |
|
||||
| TError | |
|
||||
|
|
@ -62,6 +62,9 @@ steps:
|
|||
- script: cd packages/samples && npm run regen-samples
|
||||
displayName: Regenerate Samples
|
||||
|
||||
- script: node common/scripts/install-run-rush.js regen-docs
|
||||
displayName: Regenerate Reference Docs
|
||||
|
||||
- script: node eng/scripts/check-for-changed-files.js
|
||||
displayName: Check Git Status For Changed Files
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,19 @@
|
|||
#!/usr/bin/env node
|
||||
// @ts-check
|
||||
import { join } from "path";
|
||||
import { generateDocs } from "../../packages/ref-doc/dist/src/index.js";
|
||||
import { repoRoot } from "./helpers.js";
|
||||
|
||||
// Rest
|
||||
await generateDocs(
|
||||
join(repoRoot, "packages/rest/lib/rest.cadl"),
|
||||
["Cadl.Http", "Cadl.Rest", "Cadl.Rest.Resource"],
|
||||
join(repoRoot, "docs/standard-library/rest/reference")
|
||||
);
|
||||
|
||||
// OpenAPI
|
||||
await generateDocs(
|
||||
join(repoRoot, "packages/openapi/lib/main.cadl"),
|
||||
["OpenAPI"],
|
||||
join(repoRoot, "docs/standard-library/openapi/reference")
|
||||
);
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
import { Program } from "./program.js";
|
||||
import { isTemplateDeclaration } from "./type-utils.js";
|
||||
import {
|
||||
Decorator,
|
||||
Enum,
|
||||
Interface,
|
||||
ListenerFlow,
|
||||
|
|
@ -186,6 +187,10 @@ function navigateNamespaceType(namespace: Namespace, context: NavigationContext)
|
|||
for (const enumType of namespace.enums.values()) {
|
||||
navigateEnumType(enumType, context);
|
||||
}
|
||||
|
||||
for (const decorator of namespace.decoratorDeclarations.values()) {
|
||||
navigateDecoratorDeclaration(decorator, context);
|
||||
}
|
||||
}
|
||||
|
||||
function checkVisited(visited: Set<any>, item: any) {
|
||||
|
|
@ -310,6 +315,13 @@ function navigateTemplateParameter(type: TemplateParameter, context: NavigationC
|
|||
if (context.emit("templateParameter", type) === ListenerFlow.NoRecursion) return;
|
||||
}
|
||||
|
||||
function navigateDecoratorDeclaration(type: Decorator, context: NavigationContext) {
|
||||
if (checkVisited(context.visited, type)) {
|
||||
return;
|
||||
}
|
||||
if (context.emit("decorator", type) === ListenerFlow.NoRecursion) return;
|
||||
}
|
||||
|
||||
function navigateTypeInternal(type: Type, context: NavigationContext) {
|
||||
switch (type.kind) {
|
||||
case "Model":
|
||||
|
|
@ -334,10 +346,11 @@ function navigateTypeInternal(type: Type, context: NavigationContext) {
|
|||
return navigateTupleType(type, context);
|
||||
case "TemplateParameter":
|
||||
return navigateTemplateParameter(type, context);
|
||||
case "Decorator":
|
||||
return navigateDecoratorDeclaration(type, context);
|
||||
case "Object":
|
||||
case "Projection":
|
||||
case "Function":
|
||||
case "Decorator":
|
||||
case "FunctionParameter":
|
||||
case "Boolean":
|
||||
case "EnumMember":
|
||||
|
|
|
|||
|
|
@ -74,7 +74,9 @@ export function isTemplateInstance(
|
|||
/**
|
||||
* Resolve if the type is a template type declaration(Non initialized template type).
|
||||
*/
|
||||
export function isTemplateDeclaration(type: TemplatedType): boolean {
|
||||
export function isTemplateDeclaration(
|
||||
type: TemplatedType
|
||||
): type is TemplatedType & { node: TemplateDeclarationNode } {
|
||||
if (type.node === undefined) {
|
||||
return false;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -33,6 +33,8 @@ extern dec doc(target: unknown, doc: string, formatArgs?: object);
|
|||
* Mark this type as deprecated
|
||||
* @param message Deprecation message.
|
||||
*
|
||||
* @example
|
||||
*
|
||||
* ```cadl
|
||||
* @deprecated("Use ActionV2")
|
||||
* op Action<T>(): T;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
require("@cadl-lang/eslint-config-cadl/patch/modern-module-resolution");
|
||||
|
||||
module.exports = {
|
||||
plugins: [],
|
||||
extends: ["@cadl-lang/eslint-config-cadl"],
|
||||
parserOptions: { tsconfigRootDir: __dirname },
|
||||
};
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) Microsoft Corporation. All rights reserved.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
#!/bin/bash
|
||||
set -x
|
||||
|
||||
dir_path=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
|
||||
|
||||
repo_root=$dir_path/../../
|
||||
echo "Repo root: $repo_root"
|
||||
|
||||
# Compiler decorators
|
||||
# node $dir_path/dist/src/cli.js $repo_root/docs/standard-library
|
||||
node $dir_path/dist/src/cli.js $repo_root/packages/rest/lib/rest.cadl $repo_root/docs/standard-library/rest/reference Cadl.Http Cadl.Rest Cadl.Rest.Resource
|
||||
node $dir_path/dist/src/cli.js $repo_root/packages/openapi/lib/main.cadl $repo_root/docs/standard-library/openapi/reference OpenAPI
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
{
|
||||
"name": "@cadl-lang/ref-doc",
|
||||
"version": "0.1.0",
|
||||
"author": "Microsoft Corporation",
|
||||
"description": "Cadl library for generating cadl docs",
|
||||
"homepage": "https://github.com/Microsoft/cadl",
|
||||
"readme": "https://github.com/Microsoft/cadl/blob/master/README.md",
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/Microsoft/cadl.git"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/Microsoft/cadl/issues"
|
||||
},
|
||||
"keywords": [
|
||||
"cadl"
|
||||
],
|
||||
"type": "module",
|
||||
"main": "dist/src/index.js",
|
||||
"exports": {
|
||||
".": "./dist/src/index.js"
|
||||
},
|
||||
"typesVersions": {
|
||||
"*": {
|
||||
"*": [
|
||||
"./dist/src/index.d.ts"
|
||||
]
|
||||
}
|
||||
},
|
||||
"cadlMain": "dist/src/index.js",
|
||||
"engines": {
|
||||
"node": ">=16.0.0"
|
||||
},
|
||||
"scripts": {
|
||||
"clean": "rimraf ./dist ./temp",
|
||||
"build": "tsc -p .",
|
||||
"watch": "tsc -p . --watch",
|
||||
"test": "echo 'no tests'",
|
||||
"test-official": "echo 'no tests'",
|
||||
"lint": "eslint . --ext .ts --max-warnings=0",
|
||||
"lint:fix": "eslint . --fix --ext .ts"
|
||||
},
|
||||
"files": [
|
||||
"lib/*.cadl",
|
||||
"dist/**",
|
||||
"!dist/test/**"
|
||||
],
|
||||
"dependencies": {
|
||||
"@cadl-lang/compiler": "~0.38.3",
|
||||
"prettier": "~2.7.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@cadl-lang/compiler": "~0.38.3",
|
||||
"@cadl-lang/eslint-config-cadl": "~0.5.0",
|
||||
"@types/mocha": "~10.0.0",
|
||||
"@types/node": "~18.11.9",
|
||||
"c8": "~7.12.0",
|
||||
"eslint": "^8.12.0",
|
||||
"mocha": "~10.1.0",
|
||||
"mocha-junit-reporter": "~2.2.0",
|
||||
"mocha-multi-reporters": "~1.5.1",
|
||||
"rimraf": "~3.0.2",
|
||||
"typescript": "~4.9.3",
|
||||
"@types/prettier": "2.6.0"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
/* eslint-disable no-console */
|
||||
import { normalizePath } from "@cadl-lang/compiler";
|
||||
import { resolve } from "path";
|
||||
import { generateDocs } from "./index.js";
|
||||
|
||||
main().catch((e) => {
|
||||
console.error(e);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
async function main() {
|
||||
const args = process.argv.slice(2);
|
||||
const entrypoint = args[0];
|
||||
const outputDir = args[1];
|
||||
const namespaces = args.slice(2);
|
||||
if (entrypoint === undefined) {
|
||||
console.error("Specify doc entrypoint as 1st parameter");
|
||||
process.exit(1);
|
||||
}
|
||||
if (outputDir === undefined) {
|
||||
console.error("Specify output-dir as 2nd parameter");
|
||||
process.exit(1);
|
||||
}
|
||||
const main = normalizePath(resolve(entrypoint));
|
||||
const resolvedOutputDir = normalizePath(resolve(outputDir));
|
||||
console.log(`Generate docs`, {
|
||||
main,
|
||||
resolvedOutputDir,
|
||||
});
|
||||
|
||||
await generateDocs(main, namespaces, resolvedOutputDir);
|
||||
}
|
||||
|
|
@ -0,0 +1,329 @@
|
|||
import prettier from "prettier";
|
||||
import {
|
||||
CadlRefDoc,
|
||||
DecoratorRefDoc,
|
||||
EnumRefDoc,
|
||||
InterfaceRefDoc,
|
||||
ModelRefDoc,
|
||||
NamespaceRefDoc,
|
||||
OperationRefDoc,
|
||||
TemplateParameterRefDoc,
|
||||
UnionRefDoc,
|
||||
} from "../types.js";
|
||||
import { codeblock, headings, inlinecode, table } from "../utils/markdown.js";
|
||||
import { getTypeSignature } from "../utils/type-signature.js";
|
||||
|
||||
/**
|
||||
* Render doc to a markdown using docusaurus addons.
|
||||
*/
|
||||
export function renderToDocusaurusMarkdown(refDoc: CadlRefDoc): Record<string, string> {
|
||||
const files: Record<string, string> = {
|
||||
"index.md": renderIndexFile(refDoc),
|
||||
};
|
||||
|
||||
const decoratorFile = renderDecoratorFile(refDoc);
|
||||
if (decoratorFile) {
|
||||
files["decorators.md"] = decoratorFile;
|
||||
}
|
||||
|
||||
const interfaceFile = renderInterfacesFile(refDoc);
|
||||
if (interfaceFile) {
|
||||
files["interfaces.md"] = interfaceFile;
|
||||
}
|
||||
|
||||
const dataTypes = renderDataTypes(refDoc);
|
||||
if (dataTypes) {
|
||||
files["data-types.md"] = dataTypes;
|
||||
}
|
||||
|
||||
for (const [file, content] of Object.entries(files)) {
|
||||
try {
|
||||
files[file] = prettier.format(content, {
|
||||
parser: "markdown",
|
||||
});
|
||||
} catch (e) {
|
||||
// eslint-disable-next-line no-console
|
||||
console.error(`Cannot format with prettier ${file}`);
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
function renderIndexFile(refDoc: CadlRefDoc): string {
|
||||
const content = [
|
||||
"---",
|
||||
`title: Index`,
|
||||
`sidebar_position: 0`,
|
||||
"toc_min_heading_level: 2",
|
||||
"toc_max_heading_level: 3",
|
||||
"---",
|
||||
];
|
||||
|
||||
for (const namespace of refDoc.namespaces) {
|
||||
content.push(headings.h2(namespace.id), "");
|
||||
if (namespace.decorators.length > 0) {
|
||||
content.push(headings.h3("Decorators"), "");
|
||||
for (const decorator of namespace.decorators) {
|
||||
content.push(` - [${inlinecode(decorator.name)}](./decorators.md#${decorator.id})`);
|
||||
}
|
||||
}
|
||||
|
||||
if (namespace.interfaces.length > 0) {
|
||||
content.push(headings.h3("Interfaces"), "");
|
||||
for (const iface of namespace.interfaces) {
|
||||
content.push(` - [${inlinecode(iface.name)}](./interfaces.md#${iface.id})`);
|
||||
}
|
||||
}
|
||||
|
||||
if (namespace.operations.length > 0) {
|
||||
content.push(headings.h3("Operations"), "");
|
||||
for (const operation of namespace.operations) {
|
||||
content.push(` - [${inlinecode(operation.name)}](./interfaces.md#${operation.id})`);
|
||||
}
|
||||
}
|
||||
|
||||
if (namespace.models.length > 0) {
|
||||
content.push(headings.h3("Models"), "");
|
||||
for (const model of namespace.models) {
|
||||
content.push(` - [${inlinecode(model.name)}](./data-types.md#${model.id})`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderDecoratorFile(refDoc: CadlRefDoc): string | undefined {
|
||||
if (!refDoc.namespaces.some((x) => x.decorators.length > 0)) {
|
||||
return undefined;
|
||||
}
|
||||
const content = [
|
||||
"---",
|
||||
`title: "Decorators"`,
|
||||
"toc_min_heading_level: 2",
|
||||
"toc_max_heading_level: 3",
|
||||
"---",
|
||||
headings.h1("Decorators"),
|
||||
];
|
||||
|
||||
content.push(
|
||||
groupByNamespace(refDoc.namespaces, (namespace) => {
|
||||
if (namespace.decorators.length === 0) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const content = [];
|
||||
for (const dec of namespace.decorators) {
|
||||
content.push(renderDecoratorMarkdown(dec), "");
|
||||
}
|
||||
return content.join("\n");
|
||||
})
|
||||
);
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderDecoratorMarkdown(dec: DecoratorRefDoc, headingLevel: number = 3): string {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(dec.name)} {#${dec.id}}`),
|
||||
"",
|
||||
dec.doc,
|
||||
codeblock(dec.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
content.push(
|
||||
headings.hx(headingLevel + 1, "Target"),
|
||||
dec.target.doc,
|
||||
inlinecode(getTypeSignature(dec.target.type.type)),
|
||||
""
|
||||
);
|
||||
|
||||
const paramTable: string[][] = [["Name", "Type", "Description"]];
|
||||
for (const param of dec.parameters) {
|
||||
paramTable.push([param.name, inlinecode(getTypeSignature(param.type.type)), param.doc]);
|
||||
}
|
||||
content.push(headings.hx(headingLevel + 1, "Parameters"), table(paramTable), "");
|
||||
|
||||
if (dec.examples.length > 0) {
|
||||
content.push(headings.hx(headingLevel + 1, "Examples"));
|
||||
for (const example of dec.examples) {
|
||||
if (example.title) {
|
||||
content.push(headings.hx(headingLevel + 2, example.title));
|
||||
}
|
||||
content.push("", example.content, "");
|
||||
}
|
||||
}
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderInterfacesFile(refDoc: CadlRefDoc): string | undefined {
|
||||
if (!refDoc.namespaces.some((x) => x.operations.length > 0 || x.interfaces.length > 0)) {
|
||||
return undefined;
|
||||
}
|
||||
const content = [
|
||||
"---",
|
||||
`title: "Interfaces and Operations"`,
|
||||
"toc_min_heading_level: 2",
|
||||
"toc_max_heading_level: 3",
|
||||
"---",
|
||||
headings.h1("Interfaces and Operations"),
|
||||
];
|
||||
|
||||
content.push(
|
||||
groupByNamespace(refDoc.namespaces, (namespace) => {
|
||||
if (namespace.operations.length === 0 && namespace.interfaces.length === 0) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const content = [];
|
||||
for (const iface of namespace.interfaces) {
|
||||
content.push(renderInterfaceMarkdown(iface), "");
|
||||
}
|
||||
|
||||
for (const operation of namespace.operations) {
|
||||
content.push(renderOperationMarkdown(operation), "");
|
||||
}
|
||||
return content.join("\n");
|
||||
})
|
||||
);
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderOperationMarkdown(op: OperationRefDoc, headingLevel: number = 3) {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(op.name)} {#${op.id}}`),
|
||||
"",
|
||||
op.doc,
|
||||
codeblock(op.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
if (op.templateParameters) {
|
||||
content.push(renderTemplateParametersTable(op.templateParameters, headingLevel + 1));
|
||||
}
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderTemplateParametersTable(
|
||||
templateParameters: TemplateParameterRefDoc[],
|
||||
headingLevel: number
|
||||
) {
|
||||
const paramTable: string[][] = [["Name", "Description"]];
|
||||
for (const param of templateParameters) {
|
||||
paramTable.push([param.name, param.doc]);
|
||||
}
|
||||
|
||||
return [headings.hx(headingLevel, "Template Parameters"), table(paramTable), ""].join("\n");
|
||||
}
|
||||
|
||||
function renderInterfaceMarkdown(iface: InterfaceRefDoc, headingLevel: number = 3) {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(iface.name)} {#${iface.id}}`),
|
||||
"",
|
||||
iface.doc,
|
||||
codeblock(iface.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
if (iface.templateParameters) {
|
||||
content.push(renderTemplateParametersTable(iface.templateParameters, headingLevel + 1));
|
||||
}
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderDataTypes(refDoc: CadlRefDoc): string | undefined {
|
||||
if (!refDoc.namespaces.some((x) => x.models.length > 0)) {
|
||||
return undefined;
|
||||
}
|
||||
const content = [
|
||||
"---",
|
||||
`title: "Data types"`,
|
||||
"toc_min_heading_level: 2",
|
||||
"toc_max_heading_level: 3",
|
||||
"---",
|
||||
headings.h1("Data types"),
|
||||
];
|
||||
|
||||
content.push(
|
||||
groupByNamespace(refDoc.namespaces, (namespace) => {
|
||||
if (namespace.models.length === 0) {
|
||||
return undefined;
|
||||
}
|
||||
const content = [];
|
||||
for (const model of namespace.models) {
|
||||
content.push(renderModel(model), "");
|
||||
}
|
||||
for (const e of namespace.enums) {
|
||||
content.push(renderEnum(e), "");
|
||||
}
|
||||
for (const union of namespace.unions) {
|
||||
content.push(renderUnion(union), "");
|
||||
}
|
||||
return content.join("\n");
|
||||
})
|
||||
);
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderModel(model: ModelRefDoc, headingLevel: number = 3): string {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(model.name)} {#${model.id}}`),
|
||||
"",
|
||||
model.doc,
|
||||
codeblock(model.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
if (model.templateParameters) {
|
||||
content.push(renderTemplateParametersTable(model.templateParameters, headingLevel + 1));
|
||||
}
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function renderEnum(e: EnumRefDoc, headingLevel: number = 3): string {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(e.name)} {#${e.id}}`),
|
||||
"",
|
||||
e.doc,
|
||||
codeblock(e.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
function renderUnion(union: UnionRefDoc, headingLevel: number = 3): string {
|
||||
const content = [
|
||||
headings.hx(headingLevel, `${inlinecode(union.name)} {#${union.id}}`),
|
||||
"",
|
||||
union.doc,
|
||||
codeblock(union.signature, "cadl"),
|
||||
"",
|
||||
];
|
||||
|
||||
if (union.templateParameters) {
|
||||
content.push(renderTemplateParametersTable(union.templateParameters, headingLevel + 1));
|
||||
}
|
||||
|
||||
return content.join("\n");
|
||||
}
|
||||
|
||||
function groupByNamespace(
|
||||
namespaces: NamespaceRefDoc[],
|
||||
callback: (namespace: NamespaceRefDoc) => string | undefined
|
||||
): string {
|
||||
const content = [];
|
||||
for (const namespace of namespaces) {
|
||||
const contentForNamespace = callback(namespace);
|
||||
if (contentForNamespace) {
|
||||
content.push(headings.h2(namespace.id), "");
|
||||
content.push(contentForNamespace, "");
|
||||
}
|
||||
}
|
||||
return content.join("\n");
|
||||
}
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
import { compile, joinPaths, NodeHost } from "@cadl-lang/compiler";
|
||||
import { mkdir, writeFile } from "fs/promises";
|
||||
import { renderToDocusaurusMarkdown } from "./emitters/docusaurus.js";
|
||||
import { extractRefDocs } from "./extractor.js";
|
||||
|
||||
/**
|
||||
* @experimental this is for experimental and is for internal use only. Breaking change to this API can happen at anytime.
|
||||
*/
|
||||
export async function generateDocs(main: string, namespaces: string[], outputDir: string) {
|
||||
const program = await compile(NodeHost, main, {
|
||||
parseOptions: { comments: true, docs: true },
|
||||
});
|
||||
const refDoc = extractRefDocs(program, namespaces);
|
||||
const files = renderToDocusaurusMarkdown(refDoc);
|
||||
await mkdir(outputDir, { recursive: true });
|
||||
for (const [name, content] of Object.entries(files)) {
|
||||
await writeFile(joinPaths(outputDir, name), content);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,298 @@
|
|||
import {
|
||||
compilerAssert,
|
||||
Decorator,
|
||||
DocContent,
|
||||
DocUnknownTagNode,
|
||||
Enum,
|
||||
getDoc,
|
||||
getSourceLocation,
|
||||
getTypeName,
|
||||
ignoreDiagnostics,
|
||||
Interface,
|
||||
isTemplateDeclaration,
|
||||
Model,
|
||||
Namespace,
|
||||
navigateTypesInNamespace,
|
||||
Operation,
|
||||
Program,
|
||||
SyntaxKind,
|
||||
TemplatedType,
|
||||
Type,
|
||||
Union,
|
||||
} from "@cadl-lang/compiler";
|
||||
import {
|
||||
CadlRefDoc,
|
||||
DecoratorRefDoc,
|
||||
EnumRefDoc,
|
||||
ExampleRefDoc,
|
||||
FunctionParameterRefDoc,
|
||||
InterfaceRefDoc,
|
||||
ModelRefDoc,
|
||||
NamespaceRefDoc,
|
||||
OperationRefDoc,
|
||||
UnionRefDoc,
|
||||
} from "./types.js";
|
||||
import { getQualifier, getTypeSignature } from "./utils/type-signature.js";
|
||||
|
||||
export function extractRefDocs(program: Program, filterToNamespace: string[] = []): CadlRefDoc {
|
||||
const namespaceTypes = filterToNamespace
|
||||
.map((x) => ignoreDiagnostics(program.resolveTypeReference(x)))
|
||||
.filter((x): x is Namespace => x !== undefined);
|
||||
|
||||
const refDoc: CadlRefDoc = {
|
||||
namespaces: [],
|
||||
};
|
||||
|
||||
for (const namespace of namespaceTypes) {
|
||||
const namespaceDoc: NamespaceRefDoc = {
|
||||
id: getTypeName(namespace),
|
||||
decorators: [],
|
||||
operations: [],
|
||||
interfaces: [],
|
||||
models: [],
|
||||
enums: [],
|
||||
unions: [],
|
||||
};
|
||||
refDoc.namespaces.push(namespaceDoc);
|
||||
navigateTypesInNamespace(
|
||||
namespace,
|
||||
{
|
||||
decorator(dec) {
|
||||
namespaceDoc.decorators.push(extractDecoratorRefDoc(program, dec));
|
||||
},
|
||||
operation(operation) {
|
||||
if (operation.interface === undefined) {
|
||||
namespaceDoc.operations.push(extractOperationRefDoc(program, operation));
|
||||
}
|
||||
},
|
||||
interface(iface) {
|
||||
namespaceDoc.interfaces.push(extractInterfaceRefDocs(program, iface));
|
||||
},
|
||||
model(model) {
|
||||
if (model.name === "") {
|
||||
return;
|
||||
}
|
||||
namespaceDoc.models.push(extractModelRefDocs(program, model));
|
||||
},
|
||||
enum(e) {
|
||||
namespaceDoc.enums.push(extractEnumRefDoc(program, e));
|
||||
},
|
||||
union(union) {
|
||||
if (union.name !== undefined) {
|
||||
namespaceDoc.unions.push(extractUnionRefDocs(program, union as any));
|
||||
}
|
||||
},
|
||||
},
|
||||
{ includeTemplateDeclaration: true, skipSubNamespaces: true }
|
||||
);
|
||||
}
|
||||
|
||||
return refDoc;
|
||||
}
|
||||
|
||||
function extractTemplateParameterDocs(type: TemplatedType) {
|
||||
if (isTemplateDeclaration(type)) {
|
||||
const templateParamsDocs = getTemplateParameterDocs(type);
|
||||
return type.node!.templateParameters.map((x) => ({
|
||||
name: x.id.sv,
|
||||
doc: templateParamsDocs.get(x.id.sv) ?? "",
|
||||
}));
|
||||
} else {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function extractInterfaceRefDocs(program: Program, iface: Interface): InterfaceRefDoc {
|
||||
return {
|
||||
id: getNamedTypeId(iface),
|
||||
name: iface.name,
|
||||
signature: getTypeSignature(iface),
|
||||
type: iface,
|
||||
templateParameters: extractTemplateParameterDocs(iface),
|
||||
doc: extractMainDoc(program, iface),
|
||||
examples: extractExamples(iface),
|
||||
};
|
||||
}
|
||||
|
||||
function extractOperationRefDoc(program: Program, operation: Operation): OperationRefDoc {
|
||||
return {
|
||||
id: getNamedTypeId(operation),
|
||||
name: operation.name,
|
||||
signature: getTypeSignature(operation),
|
||||
type: operation,
|
||||
templateParameters: extractTemplateParameterDocs(operation),
|
||||
doc: extractMainDoc(program, operation),
|
||||
examples: extractExamples(operation),
|
||||
};
|
||||
}
|
||||
|
||||
function extractDecoratorRefDoc(program: Program, decorator: Decorator): DecoratorRefDoc {
|
||||
const paramDoc = getParmeterDocs(decorator);
|
||||
const parameters: FunctionParameterRefDoc[] = decorator.parameters.map((x) => {
|
||||
return {
|
||||
type: x,
|
||||
doc: paramDoc.get(x.name) ?? "",
|
||||
name: x.name,
|
||||
optional: x.optional,
|
||||
rest: x.rest,
|
||||
};
|
||||
});
|
||||
|
||||
const examples = extractExamples(decorator);
|
||||
return {
|
||||
id: getNamedTypeId(decorator),
|
||||
name: decorator.name,
|
||||
type: decorator,
|
||||
signature: getTypeSignature(decorator),
|
||||
doc: extractMainDoc(program, decorator),
|
||||
parameters,
|
||||
examples,
|
||||
otherTags: [],
|
||||
target: {
|
||||
type: decorator.target,
|
||||
doc: paramDoc.get(decorator.target.name) ?? "",
|
||||
name: decorator.target.name,
|
||||
optional: decorator.target.optional,
|
||||
rest: decorator.target.rest,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function extractModelRefDocs(program: Program, type: Model): ModelRefDoc {
|
||||
return {
|
||||
id: getNamedTypeId(type),
|
||||
name: type.name,
|
||||
signature: getTypeSignature(type),
|
||||
type,
|
||||
templateParameters: extractTemplateParameterDocs(type),
|
||||
doc: extractMainDoc(program, type),
|
||||
examples: extractExamples(type),
|
||||
};
|
||||
}
|
||||
|
||||
function extractEnumRefDoc(program: Program, type: Enum): EnumRefDoc {
|
||||
return {
|
||||
id: getNamedTypeId(type),
|
||||
name: type.name,
|
||||
signature: getTypeSignature(type),
|
||||
type,
|
||||
doc: extractMainDoc(program, type),
|
||||
examples: extractExamples(type),
|
||||
};
|
||||
}
|
||||
function extractUnionRefDocs(program: Program, type: Union & { name: string }): UnionRefDoc {
|
||||
return {
|
||||
id: getNamedTypeId(type),
|
||||
name: type.name,
|
||||
signature: getTypeSignature(type),
|
||||
type,
|
||||
templateParameters: extractTemplateParameterDocs(type),
|
||||
doc: extractMainDoc(program, type),
|
||||
examples: extractExamples(type),
|
||||
};
|
||||
}
|
||||
|
||||
function extractMainDoc(program: Program, type: Type): string {
|
||||
let mainDoc: string = "";
|
||||
for (const doc of type.node?.docs ?? []) {
|
||||
for (const dContent of doc.content) {
|
||||
mainDoc += dContent.text + "\n";
|
||||
}
|
||||
}
|
||||
return mainDoc !== "" ? mainDoc : getDoc(program, type) ?? "";
|
||||
}
|
||||
|
||||
function extractExamples(type: Type): ExampleRefDoc[] {
|
||||
const examples: ExampleRefDoc[] = [];
|
||||
for (const doc of type.node?.docs ?? []) {
|
||||
for (const dTag of doc.tags) {
|
||||
if (dTag.kind === SyntaxKind.DocUnknownTag)
|
||||
if (dTag.tagName.sv === "example") {
|
||||
examples.push(extractExample(dTag));
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
return examples;
|
||||
}
|
||||
|
||||
function getNamedTypeId(type: Type & { name: string }) {
|
||||
switch (type.kind) {
|
||||
case "Decorator":
|
||||
return getDecoratorId(type);
|
||||
case "Operation":
|
||||
return getQualifier(type.interface ?? type.namespace) + type.name;
|
||||
default:
|
||||
return "namespace" in type ? getQualifier(type.namespace) + type.name : type.name;
|
||||
}
|
||||
}
|
||||
|
||||
function getDecoratorId(decorator: Decorator) {
|
||||
return "@" + getQualifier(decorator.namespace) + decorator.name.slice(1);
|
||||
}
|
||||
|
||||
function checkIfTagHasDocOnSameLine(tag: DocUnknownTagNode): boolean {
|
||||
const start = tag.content[0]?.pos;
|
||||
const end = tag.content[0]?.end;
|
||||
const file = getSourceLocation(tag.content[0]).file;
|
||||
|
||||
let hasFirstLine = false;
|
||||
for (let i = start; i < end; i++) {
|
||||
const ch = file.text[i];
|
||||
if (ch === "\n") {
|
||||
break;
|
||||
}
|
||||
// Todo reuse compiler whitespace logic or have a way to get this info from the parser.
|
||||
if (ch !== " ") {
|
||||
hasFirstLine = true;
|
||||
}
|
||||
}
|
||||
return hasFirstLine;
|
||||
}
|
||||
|
||||
function extractExample(tag: DocUnknownTagNode): ExampleRefDoc {
|
||||
const content = getDocContent(tag.content);
|
||||
const hasInfoOnFirstLine = checkIfTagHasDocOnSameLine(tag);
|
||||
if (hasInfoOnFirstLine) {
|
||||
const [title, ...contents] = content.split("\n");
|
||||
return { title, content: contents.join("\n") };
|
||||
} else {
|
||||
return { content };
|
||||
}
|
||||
}
|
||||
|
||||
function getParmeterDocs(type: Type): Map<string, string> {
|
||||
const map = new Map<string, string>();
|
||||
for (const d of type?.node?.docs ?? []) {
|
||||
for (const tag of d.tags) {
|
||||
if (tag.kind === SyntaxKind.DocParamTag) {
|
||||
map.set(tag.paramName.sv, getDocContent(tag.content));
|
||||
}
|
||||
}
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
function getTemplateParameterDocs(type: Type): Map<string, string> {
|
||||
const map = new Map<string, string>();
|
||||
for (const d of type?.node?.docs ?? []) {
|
||||
for (const tag of d.tags) {
|
||||
if (tag.kind === SyntaxKind.DocTemplateTag) {
|
||||
map.set(tag.paramName.sv, getDocContent(tag.content));
|
||||
}
|
||||
}
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
function getDocContent(content: readonly DocContent[]) {
|
||||
const docs = [];
|
||||
for (const node of content) {
|
||||
compilerAssert(
|
||||
node.kind === SyntaxKind.DocText,
|
||||
"No other doc content node kinds exist yet. Update this code appropriately when more are added."
|
||||
);
|
||||
docs.push(node.text);
|
||||
}
|
||||
return docs.join("");
|
||||
}
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
export * from "./experimental.js";
|
||||
export * from "./extractor.js";
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
import {
|
||||
Decorator,
|
||||
Enum,
|
||||
FunctionParameter,
|
||||
Interface,
|
||||
Model,
|
||||
Operation,
|
||||
Union,
|
||||
} from "@cadl-lang/compiler";
|
||||
|
||||
export type CadlRefDoc = {
|
||||
namespaces: NamespaceRefDoc[];
|
||||
};
|
||||
|
||||
export type NamespaceRefDoc = {
|
||||
id: string;
|
||||
decorators: DecoratorRefDoc[];
|
||||
operations: OperationRefDoc[];
|
||||
interfaces: InterfaceRefDoc[];
|
||||
models: ModelRefDoc[];
|
||||
enums: EnumRefDoc[];
|
||||
unions: UnionRefDoc[];
|
||||
};
|
||||
|
||||
export type NamedTypeRefDoc = {
|
||||
/**
|
||||
* Fully qualified id
|
||||
*/
|
||||
id: string;
|
||||
|
||||
name: string;
|
||||
signature: string;
|
||||
doc: string;
|
||||
examples: ExampleRefDoc[];
|
||||
};
|
||||
|
||||
export type DecoratorRefDoc = NamedTypeRefDoc & {
|
||||
type: Decorator;
|
||||
target: FunctionParameterRefDoc;
|
||||
parameters: FunctionParameterRefDoc[];
|
||||
otherTags: string[];
|
||||
};
|
||||
|
||||
export type FunctionParameterRefDoc = {
|
||||
type: FunctionParameter;
|
||||
name: string;
|
||||
doc: string;
|
||||
optional: boolean;
|
||||
rest: boolean;
|
||||
};
|
||||
|
||||
export type ExampleRefDoc = {
|
||||
title?: string;
|
||||
content: string;
|
||||
};
|
||||
|
||||
export type OperationRefDoc = NamedTypeRefDoc & {
|
||||
type: Operation;
|
||||
|
||||
templateParameters?: TemplateParameterRefDoc[];
|
||||
};
|
||||
|
||||
export type InterfaceRefDoc = NamedTypeRefDoc & {
|
||||
type: Interface;
|
||||
templateParameters?: TemplateParameterRefDoc[];
|
||||
};
|
||||
|
||||
export type TemplateParameterRefDoc = {
|
||||
name: string;
|
||||
doc: string;
|
||||
};
|
||||
|
||||
export type ModelRefDoc = NamedTypeRefDoc & {
|
||||
type: Model;
|
||||
|
||||
templateParameters?: TemplateParameterRefDoc[];
|
||||
};
|
||||
|
||||
export type EnumRefDoc = NamedTypeRefDoc & {
|
||||
type: Enum;
|
||||
};
|
||||
|
||||
export type UnionRefDoc = NamedTypeRefDoc & {
|
||||
type: Union;
|
||||
|
||||
templateParameters?: TemplateParameterRefDoc[];
|
||||
};
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
export const headings = {
|
||||
h1: hx(1),
|
||||
h2: hx(2),
|
||||
h3: hx(3),
|
||||
h4: hx(4),
|
||||
h5: hx(5),
|
||||
hx: (number: number, title: string) => {
|
||||
return "#".repeat(number) + " " + title;
|
||||
},
|
||||
};
|
||||
|
||||
function hx(number: number) {
|
||||
const prefix = "#".repeat(number) + " ";
|
||||
return (title: string) => prefix + title;
|
||||
}
|
||||
|
||||
export function codeblock(code: string, lang: string = "") {
|
||||
return "```" + lang + "\n" + code + "\n" + "```";
|
||||
}
|
||||
|
||||
export function inlinecode(code: string) {
|
||||
return "`" + code + "`";
|
||||
}
|
||||
|
||||
export function table([header, ...rows]: string[][]) {
|
||||
const renderRow = (row: string[]): string => `| ${row.join(" | ")} |`;
|
||||
|
||||
return [
|
||||
renderRow(header),
|
||||
"|" + header.map((x) => "-".repeat(x.length + 2)).join("|") + "|",
|
||||
...rows.map(renderRow),
|
||||
].join("\n");
|
||||
}
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
import {
|
||||
compilerAssert,
|
||||
Decorator,
|
||||
EnumMember,
|
||||
FunctionParameter,
|
||||
FunctionType,
|
||||
getTypeName,
|
||||
Interface,
|
||||
Model,
|
||||
ModelProperty,
|
||||
Operation,
|
||||
TemplateParameterDeclarationNode,
|
||||
Type,
|
||||
UnionVariant,
|
||||
} from "@cadl-lang/compiler";
|
||||
|
||||
/** @internal */
|
||||
export function getTypeSignature(type: Type): string {
|
||||
if (isReflectionType(type)) {
|
||||
return type.name;
|
||||
}
|
||||
switch (type.kind) {
|
||||
case "Scalar":
|
||||
case "Enum":
|
||||
case "Union":
|
||||
case "Model":
|
||||
case "Namespace":
|
||||
return `${type.kind.toLowerCase()} ${getTypeName(type)}`;
|
||||
case "Interface":
|
||||
return getInterfaceSignature(type);
|
||||
case "Decorator":
|
||||
return getDecoratorSignature(type);
|
||||
case "Function":
|
||||
return getFunctionSignature(type);
|
||||
case "Operation":
|
||||
return getOperationSignature(type);
|
||||
case "String":
|
||||
return `(string) ${`"${type.value}"`}`;
|
||||
case "Boolean":
|
||||
return `(boolean) ${type.value ? "true" : "false"}`;
|
||||
case "Number":
|
||||
return `(number) ${type.value.toString()}`;
|
||||
case "Intrinsic":
|
||||
return `(intrinsic) ${type.name}`;
|
||||
case "FunctionParameter":
|
||||
return getFunctionParameterSignature(type);
|
||||
case "ModelProperty":
|
||||
return `(model property) ${`${type.name}: ${getTypeName(type.type)}`}`;
|
||||
case "EnumMember":
|
||||
return `(enum member) ${getEnumMemberSignature(type)}`;
|
||||
case "TemplateParameter":
|
||||
return type.node.id.sv;
|
||||
case "UnionVariant":
|
||||
return `(union variant) ${getUnionVariantSignature(type)}`;
|
||||
case "Tuple":
|
||||
return `(tuple) [${type.values.map(getTypeSignature).join(", ")}]`;
|
||||
case "Projection":
|
||||
return "(projection)";
|
||||
case "Object":
|
||||
return "(object)";
|
||||
default:
|
||||
const _assertNever: never = type;
|
||||
compilerAssert(false, "Unexpected type kind");
|
||||
}
|
||||
}
|
||||
|
||||
function isReflectionType(type: Type): type is Model & { name: "" } {
|
||||
return (
|
||||
type.kind === "Model" &&
|
||||
type.namespace?.name === "Reflection" &&
|
||||
type.namespace?.namespace?.name === "Cadl"
|
||||
);
|
||||
}
|
||||
|
||||
function getDecoratorSignature(type: Decorator) {
|
||||
const ns = getQualifier(type.namespace);
|
||||
const name = type.name.slice(1);
|
||||
const parameters = [type.target, ...type.parameters].map((x) => getFunctionParameterSignature(x));
|
||||
return `dec ${ns}${name}(${parameters.join(", ")})`;
|
||||
}
|
||||
|
||||
function getFunctionSignature(type: FunctionType) {
|
||||
const ns = getQualifier(type.namespace);
|
||||
const parameters = type.parameters.map((x) => getFunctionParameterSignature(x));
|
||||
return `fn ${ns}${type.name}(${parameters.join(", ")}): ${getTypeName(type.returnType)}`;
|
||||
}
|
||||
|
||||
function getInterfaceSignature(type: Interface) {
|
||||
const ns = getQualifier(type.namespace);
|
||||
|
||||
const templateParams = type.node.templateParameters
|
||||
? getTemplateParameters(type.node.templateParameters)
|
||||
: "";
|
||||
return `interface ${ns}${type.name}${templateParams}`;
|
||||
}
|
||||
|
||||
function getTemplateParameters(templateParameters: readonly TemplateParameterDeclarationNode[]) {
|
||||
const params = templateParameters.map((x) => `${x.id.sv}`);
|
||||
return `<${params.join(", ")}>`;
|
||||
}
|
||||
function getOperationSignature(type: Operation) {
|
||||
const qualifier = getQualifier(type.interface ?? type.namespace);
|
||||
const parameters = [...type.parameters.properties.values()].map(getModelPropertySignature);
|
||||
return `op ${qualifier}${type.name}(${parameters.join(", ")}): ${getTypeName(type.returnType)}`;
|
||||
}
|
||||
|
||||
function getFunctionParameterSignature(parameter: FunctionParameter) {
|
||||
const rest = parameter.rest ? "..." : "";
|
||||
const optional = parameter.optional ? "?" : "";
|
||||
return `${rest}${parameter.name}${optional}: ${getTypeName(parameter.type)}`;
|
||||
}
|
||||
|
||||
function getModelPropertySignature(property: ModelProperty) {
|
||||
const ns = getQualifier(property.model);
|
||||
return `${ns}${property.name}: ${getTypeName(property.type)}`;
|
||||
}
|
||||
|
||||
function getUnionVariantSignature(variant: UnionVariant) {
|
||||
if (typeof variant.name !== "string") {
|
||||
return getTypeName(variant.type);
|
||||
}
|
||||
const ns = getQualifier(variant.union);
|
||||
return `${ns}${variant.name}: ${getTypeName(variant.type)}`;
|
||||
}
|
||||
|
||||
function getEnumMemberSignature(member: EnumMember) {
|
||||
const ns = getQualifier(member.enum);
|
||||
const value = typeof member.value === "string" ? `"${member.value}"` : member.value;
|
||||
return value === undefined ? `${ns}${member.name}` : `${ns}${member.name}: ${value}`;
|
||||
}
|
||||
|
||||
export function getQualifier(parent: Type | undefined) {
|
||||
if (!parent) {
|
||||
return "";
|
||||
}
|
||||
|
||||
const parentName = getTypeName(parent);
|
||||
if (!parentName || parentName === "Cadl") {
|
||||
return "";
|
||||
}
|
||||
|
||||
return parentName + ".";
|
||||
}
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
{
|
||||
"extends": "../tsconfig.json",
|
||||
"references": [{ "path": "../compiler/tsconfig.json" }, { "path": "../rest/tsconfig.json" }],
|
||||
"compilerOptions": {
|
||||
"module": "Node16",
|
||||
"moduleResolution": "Node16",
|
||||
"outDir": "dist",
|
||||
"rootDir": ".",
|
||||
"tsBuildInfoFile": "temp/tsconfig.tsbuildinfo",
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": ["src/**/*.ts", "test/**/*.ts"]
|
||||
}
|
||||
|
|
@ -33,6 +33,11 @@ model ResourceCollectionParameters<TResource extends object> {
|
|||
...ParentKeysOf<TResource>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Represent the resource GET operation.
|
||||
* @template TResource The resource model.
|
||||
* @template TError The error response.
|
||||
*/
|
||||
@Private.validateHasKey(TResource)
|
||||
@Private.validateIsError(TError)
|
||||
interface ResourceRead<TResource extends object, TError> {
|
||||
|
|
|
|||
|
|
@ -1,5 +1,29 @@
|
|||
// @ts-check
|
||||
|
||||
/**
|
||||
*
|
||||
* @param {string} libName
|
||||
* @param {any[]} [extra]
|
||||
* @returns {any}
|
||||
*/
|
||||
function createLibraryReferenceStructure(libName, extra) {
|
||||
return {
|
||||
type: "category",
|
||||
label: "Reference",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: `standard-library/${libName}/reference/index`,
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: "autogenerated",
|
||||
dirName: `standard-library/${libName}/reference`,
|
||||
},
|
||||
...(extra ?? []),
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
|
||||
const sidebars = {
|
||||
docsSidebar: [
|
||||
|
|
@ -58,7 +82,7 @@ const sidebars = {
|
|||
label: "Http And Rest",
|
||||
items: [
|
||||
"standard-library/rest/overview",
|
||||
"standard-library/rest/decorators",
|
||||
createLibraryReferenceStructure("rest"),
|
||||
"standard-library/rest/operations",
|
||||
"standard-library/rest/authentication",
|
||||
"standard-library/rest/resource-routing",
|
||||
|
|
@ -69,9 +93,8 @@ const sidebars = {
|
|||
label: "OpenAPI",
|
||||
items: [
|
||||
"standard-library/openapi/overview",
|
||||
"standard-library/openapi/decorators",
|
||||
createLibraryReferenceStructure("rest", ["standard-library/openapi/diagnostics"]),
|
||||
"standard-library/openapi/openapi",
|
||||
"standard-library/openapi/diagnostics",
|
||||
],
|
||||
},
|
||||
],
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ export default {
|
|||
|
||||
boolean: /\b(?:false|true)\b/,
|
||||
keyword:
|
||||
/\b(?:import|model|scalar|namespace|op|interface|union|using|is|extends|enum|alias|return|void|never|if|else|projection)\b/,
|
||||
/\b(?:import|model|scalar|namespace|op|interface|union|using|is|extends|enum|alias|return|void|never|if|else|projection|dec|extern|fn)\b/,
|
||||
|
||||
function: /\b[a-z_]\w*(?=[ \t]*\()/i,
|
||||
|
||||
|
|
|
|||
|
|
@ -180,6 +180,12 @@
|
|||
"projectFolder": "packages/bundler",
|
||||
"reviewCategory": "production",
|
||||
"shouldPublish": false
|
||||
},
|
||||
{
|
||||
"packageName": "@cadl-lang/ref-doc",
|
||||
"projectFolder": "packages/ref-doc",
|
||||
"reviewCategory": "production",
|
||||
"shouldPublish": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -15,7 +15,8 @@
|
|||
{ "path": "packages/html-program-viewer/tsconfig.json" },
|
||||
{ "path": "packages/openapi3/tsconfig.json" },
|
||||
{ "path": "packages/bundler/tsconfig.json" },
|
||||
{ "path": "packages/playground/tsconfig.json" }
|
||||
{ "path": "packages/playground/tsconfig.json" },
|
||||
{ "path": "packages/ref-doc/tsconfig.json" }
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче