diff --git a/.changeset/tidy-response-schemas.md b/.changeset/tidy-response-schemas.md new file mode 100644 index 000000000..a3c71274f --- /dev/null +++ b/.changeset/tidy-response-schemas.md @@ -0,0 +1,5 @@ +--- +"@common-grants/core": minor +--- + +Add non-templated response schemas (`Ok`, `Paginated`, `Sorted`, `Filtered`, `Created`) so they are emitted as standalone JSON schemas, and rename the templated variants with a `T` suffix (`OkT`, `PaginatedT`, `SortedT`, `FilteredT`, `CreatedT`). Routes now use the `T`-suffixed templates; specs consuming the old templated names (e.g. `Responses.Ok`) must switch to the `T`-suffixed equivalents. The wire contract of route responses is unchanged. diff --git a/lib/cli/lib/openapi/openapi.0.1.0.yaml b/lib/cli/lib/openapi/openapi.0.1.0.yaml index 37b9d1a86..637b47654 100644 --- a/lib/cli/lib/openapi/openapi.0.1.0.yaml +++ b/lib/cli/lib/openapi/openapi.0.1.0.yaml @@ -35,7 +35,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -55,7 +55,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -67,7 +67,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -75,8 +75,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -89,13 +87,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -115,7 +106,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -160,7 +151,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -174,7 +165,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -953,6 +944,16 @@ components: description: Total number of pages example: 5 description: Details about the paginated results + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -973,6 +974,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/lib/cli/lib/openapi/openapi.0.2.0.yaml b/lib/cli/lib/openapi/openapi.0.2.0.yaml index 3e0f1b1ac..518f99007 100644 --- a/lib/cli/lib/openapi/openapi.0.2.0.yaml +++ b/lib/cli/lib/openapi/openapi.0.2.0.yaml @@ -33,7 +33,7 @@ paths: parameters: [] responses: '201': - description: A 201 response with data + description: A 201 response with typed data content: application/json: schema: @@ -47,7 +47,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 201 response with data + description: A 201 response with typed data '401': description: Access is unauthorized. content: @@ -92,7 +92,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -106,7 +106,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -142,7 +142,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -156,7 +156,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -187,7 +187,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -201,7 +201,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -219,7 +219,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -231,7 +231,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -271,7 +271,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -285,7 +285,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -305,7 +305,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -325,7 +325,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Forms - experimental @@ -343,7 +343,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -357,7 +357,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Forms - experimental @@ -371,7 +371,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -391,7 +391,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -403,7 +403,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -411,8 +411,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -425,13 +423,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -451,7 +442,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -496,7 +487,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -510,7 +501,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -2350,6 +2341,16 @@ components: errors: - field: formA.name message: Name is required + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -2370,6 +2371,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/lib/cli/lib/openapi/openapi.0.3.0.yaml b/lib/cli/lib/openapi/openapi.0.3.0.yaml index 486a98e61..246982740 100644 --- a/lib/cli/lib/openapi/openapi.0.3.0.yaml +++ b/lib/cli/lib/openapi/openapi.0.3.0.yaml @@ -47,7 +47,7 @@ paths: explode: false responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -55,8 +55,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -69,13 +67,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -95,7 +86,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Applications - experimental @@ -108,7 +99,7 @@ paths: parameters: [] responses: '201': - description: A 201 response with data + description: A 201 response with typed data content: application/json: schema: @@ -122,7 +113,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 201 response with data + description: A 201 response with typed data '401': description: Access is unauthorized. content: @@ -167,7 +158,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -181,7 +172,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -217,7 +208,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -231,7 +222,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -262,7 +253,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -276,7 +267,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -294,7 +285,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -306,7 +297,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -346,7 +337,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -360,7 +351,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -380,7 +371,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -400,7 +391,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Forms - experimental @@ -418,7 +409,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -432,7 +423,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Forms - experimental @@ -446,7 +437,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -466,7 +457,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -478,7 +469,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -486,8 +477,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -500,13 +489,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -526,7 +508,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -571,7 +553,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -585,7 +567,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -2542,6 +2524,16 @@ components: errors: - field: formA.name message: Name is required + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -2562,6 +2554,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/lib/core/lib/api.tsp b/lib/core/lib/api.tsp index b7ce2f462..3dc3575b7 100644 --- a/lib/core/lib/api.tsp +++ b/lib/core/lib/api.tsp @@ -71,7 +71,7 @@ namespace Opportunities { @tag("required") @returnTypeChangedFrom( CommonGrants.Versions.v0_2, - Responses.Ok | Responses.NotFound + Responses.OkT | Responses.NotFound ) op read is Router.read; diff --git a/lib/core/lib/core/responses/index.tsp b/lib/core/lib/core/responses/index.tsp index 7a46448a8..1648d5c0b 100644 --- a/lib/core/lib/core/responses/index.tsp +++ b/lib/core/lib/core/responses/index.tsp @@ -19,7 +19,7 @@ using TypeSpec.JsonSchema; * @route("/pets") * namespace Pets { * @get - * op getPets(): Responses.Ok | Responses.Unauthorized; + * op getPets(): Responses.OkT | Responses.Unauthorized; * } * ``` */ diff --git a/lib/core/lib/core/responses/success.tsp b/lib/core/lib/core/responses/success.tsp index 81cf67124..76bc9b1d5 100644 --- a/lib/core/lib/core/responses/success.tsp +++ b/lib/core/lib/core/responses/success.tsp @@ -2,6 +2,9 @@ import "../pagination.tsp"; import "../sorting.tsp"; import "@typespec/http"; +// Templated models aren't emitted as standalone JSON schemas, so each response +// family pairs a non-templated model (emitted, documented) with a `T`-suffixed +// template (used by routes). Shared `*Base` models keep the pairs in sync. namespace CommonGrants.Responses; // ############################################################################ @@ -21,7 +24,18 @@ model Success { // 200 response // ############################################################################ -/** Template for a 200 response with data +/** A 200 response with data of an unspecified shape + * + * Routes use the typed `OkT` variant. + */ +@doc("A 200 response with data") +@Versioning.added(CommonGrants.Versions.v0_1) +model Ok extends Success { + /** Response data */ + data: unknown; +} + +/** Template for a 200 response with typed data * * @template T The schema for the value of the `"data"` property in this response * @example How to specify a custom 200 response model @@ -33,13 +47,13 @@ model Success { * description: string; * } * - * // Pass that model to the `Ok` template - * alias CustomModel200 = Responses.Ok; + * // Pass that model to the `OkT` template + * alias CustomModel200 = Responses.OkT; * ``` */ -@doc("A 200 response with data") +@doc("A 200 response with typed data") @Versioning.added(CommonGrants.Versions.v0_1) -model Ok extends Success { +model OkT extends Success { // Inherit the 200 status code ...Http.OkResponse; @@ -51,7 +65,31 @@ model Ok extends Success { // 200 paginated response // ############################################################################ -/** Template for a 200 response with paginated list of items +/** Body properties shared by `Paginated` and `PaginatedT` + * + * @template T The schema for the value of the `"items"` property in this response + */ +@Versioning.added(CommonGrants.Versions.v0_1) +model PaginatedBase { + /** Items from the current page */ + @pageItems + items: T[]; + + /** Details about the paginated results */ + paginationInfo: Pagination.PaginatedResultsInfo; +} + +/** A 200 response with a paginated list of items of an unspecified shape + * + * Routes use the typed `PaginatedT` variant. + */ +@doc("A 200 response with a paginated list of items") +@Versioning.added(CommonGrants.Versions.v0_1) +model Paginated extends Success { + ...PaginatedBase; +} + +/** Template for a 200 response with a paginated list of typed items * * @template T The schema for the value of the `"items"` property in this response * @example How to specify a custom paginated response model @@ -63,29 +101,46 @@ model Ok extends Success { * description: string; * } * - * // Pass that model to the `Ok` template - * alias CustomModelResponse = Responses.Paginated; + * // Pass that model to the `PaginatedT` template + * alias CustomModelResponse = Responses.PaginatedT; * ``` */ -@doc("A 200 response with a paginated list of items") +@doc("A 200 response with a paginated list of typed items") @Versioning.added(CommonGrants.Versions.v0_1) -model Paginated extends Success { +model PaginatedT extends Success { // Inherit the 200 status code ...Http.OkResponse; - /** Items from the current page */ - @pageItems - items: T[]; - - /** Details about the paginated results */ - paginationInfo: Pagination.PaginatedResultsInfo; + ...PaginatedBase; } // ############################################################################ // 200 sorted response // ############################################################################ -/** A paginated list of items with a sort order +/** Body properties shared by `Sorted` and `SortedT` + * + * @template T The schema for the value of the `"items"` property in this response + */ +@Versioning.added(CommonGrants.Versions.v0_1) +model SortedBase { + ...PaginatedBase; + + /** The sort order of the items */ + sortInfo: Sorting.SortedResultsInfo; +} + +/** A paginated list of items of an unspecified shape with a sort order + * + * Routes use the typed `SortedT` variant. + */ +@doc("A paginated list of items with a sort order") +@Versioning.added(CommonGrants.Versions.v0_1) +model Sorted extends Success { + ...SortedBase; +} + +/** Template for a paginated list of typed items with a sort order * * @template T The schema for the value of the `"items"` property in this response * @example How to specify a custom sorted response model @@ -97,25 +152,52 @@ model Paginated extends Success { * description: string; * } * - * // Pass that model to the `Sorted` template - * alias CustomModelSortedResponse = Responses.Sorted; + * // Pass that model to the `SortedT` template + * alias CustomModelSortedResponse = Responses.SortedT; * ``` */ -@doc("A paginated list of items with a sort order") +@doc("A paginated list of typed items with a sort order") @Versioning.added(CommonGrants.Versions.v0_1) -model Sorted { - // Inherit the properties of the Paginated response - ...Paginated; +model SortedT extends Success { + // Inherit the 200 status code + ...Http.OkResponse; - /** The sort order of the items */ - sortInfo: Sorting.SortedResultsInfo; + ...SortedBase; } // ############################################################################ // 200 filtered response // ############################################################################ -/** A paginated list of items with a filter +/** Body properties shared by `Filtered` and `FilteredT` + * + * @template ItemsT The schema for the value of the `"items"` property in this response + * @template FilterT The schema for the value of the `"filter"` property in this response + */ +@Versioning.added(CommonGrants.Versions.v0_1) +model FilteredBase { + ...SortedBase; + + /** The filters applied to the response items */ + filterInfo: { + filters: FilterT; + + /** Non-fatal errors that occurred during filtering */ + errors?: string[]; + }; +} + +/** A paginated list of items of an unspecified shape with a filter + * + * Routes use the typed `FilteredT` variant. + */ +@doc("A paginated list of items with a filter") +@Versioning.added(CommonGrants.Versions.v0_1) +model Filtered extends Success { + ...FilteredBase; +} + +/** Template for a paginated list of typed items with a typed filter * * @template ItemsT The schema for the value of the `"items"` property in this response * @template FilterT The schema for the value of the `"filter"` property in this response @@ -133,35 +215,41 @@ model Sorted { * lastModifiedAt: Filters.DateComparisonFilter; * } * - * // Pass that model to the `Filtered` template - * alias CustomModelFilteredResponse = Responses.Filtered; + * // Pass that model to the `FilteredT` template + * alias CustomModelFilteredResponse = Responses.FilteredT; * ``` */ -@doc("A paginated list of items with a filter") +@doc("A paginated list of typed items with a typed filter") @Versioning.added(CommonGrants.Versions.v0_1) -model Filtered extends Success { - // Inherit the properties of the Sorted response - ...Sorted; - - /** The filters applied to the response items */ - filterInfo: { - filters: FilterT; +model FilteredT extends Success { + // Inherit the 200 status code + ...Http.OkResponse; - /** Non-fatal errors that occurred during filtering */ - errors?: string[]; - }; + ...FilteredBase; } // ############################################################################ // 201 response // ############################################################################ -/** A 201 response with data +/** A 201 response with data of an unspecified shape + * + * Routes use the typed `CreatedT` variant. + */ +@doc("A 201 response with data") +@Versioning.added(CommonGrants.Versions.v0_1) +model Created extends Success { + /** Response data */ + data: unknown; +} + +/** A 201 response with typed data * * @template T The schema for the value of the `"data"` property in this response */ +@doc("A 201 response with typed data") @Versioning.added(CommonGrants.Versions.v0_1) -model Created extends Success { +model CreatedT extends Success { // Inherit the 201 status code ...Http.CreatedResponse; diff --git a/lib/core/lib/core/routes/applications.tsp b/lib/core/lib/core/routes/applications.tsp index 11288faab..cf0b71379 100644 --- a/lib/core/lib/core/routes/applications.tsp +++ b/lib/core/lib/core/routes/applications.tsp @@ -32,7 +32,7 @@ interface Applications { /** The name of the application */ name: string, - ): Responses.Created | Responses.Unauthorized; + ): Responses.CreatedT | Responses.Unauthorized; // ############################### // Get an application @@ -46,7 +46,7 @@ interface Applications { /** The ID of the application to get */ @path appId: Types.uuid, ): - | Responses.Ok + | Responses.OkT | Responses.NotFound | Responses.Unauthorized; @@ -62,7 +62,7 @@ interface Applications { /** The ID of the application to submit */ @path appId: Types.uuid, ): - | Responses.Ok + | Responses.OkT | Responses.ApplicationSubmissionError | Responses.NotFound | Responses.Unauthorized; @@ -81,5 +81,5 @@ interface Applications { /** The sorting to apply to the search */ @query sorting: Models.AppSorting, - ): Responses.Filtered; + ): Responses.FilteredT; } diff --git a/lib/core/lib/core/routes/competitions.tsp b/lib/core/lib/core/routes/competitions.tsp index 69340e689..69b42b848 100644 --- a/lib/core/lib/core/routes/competitions.tsp +++ b/lib/core/lib/core/routes/competitions.tsp @@ -30,7 +30,7 @@ interface Competitions { read( /** The ID of the competition to view */ @path compId: Types.uuid, - ): Responses.Ok | Responses.NotFound; + ): Responses.OkT | Responses.NotFound; // ############################### // Apply to a competition @@ -47,7 +47,7 @@ interface Competitions { /** The application to apply to the competition */ @body application: Models.ApplicationBase, ): - | Responses.Created + | Responses.CreatedT | Responses.NotFound | Responses.Unauthorized; } diff --git a/lib/core/lib/core/routes/form-responses.tsp b/lib/core/lib/core/routes/form-responses.tsp index f9a967d73..fba2dd948 100644 --- a/lib/core/lib/core/routes/form-responses.tsp +++ b/lib/core/lib/core/routes/form-responses.tsp @@ -32,7 +32,7 @@ interface FormResponses { /** The response to the form */ @body response: Record, - ): Responses.Ok; + ): Responses.OkT; // ############################### // Get form response @@ -48,5 +48,5 @@ interface FormResponses { /** The ID of the form whose response is being retrieved */ @path formId: Types.uuid, - ): Responses.Ok; + ): Responses.OkT; } diff --git a/lib/core/lib/core/routes/forms.tsp b/lib/core/lib/core/routes/forms.tsp index f6545a50b..55d20f4dc 100644 --- a/lib/core/lib/core/routes/forms.tsp +++ b/lib/core/lib/core/routes/forms.tsp @@ -24,7 +24,7 @@ interface Forms { @get list( ...Pagination.PaginatedQueryParams, - ): Responses.Paginated; + ): Responses.PaginatedT; // ############################### // View form details @@ -36,5 +36,5 @@ interface Forms { read( /** The ID of the form to view */ @path formId: Types.uuid, - ): Responses.Ok; + ): Responses.OkT; } diff --git a/lib/core/lib/core/routes/opportunities.tsp b/lib/core/lib/core/routes/opportunities.tsp index 973e16fbc..86b99411e 100644 --- a/lib/core/lib/core/routes/opportunities.tsp +++ b/lib/core/lib/core/routes/opportunities.tsp @@ -50,7 +50,7 @@ interface Opportunities { @list list( ...Pagination.PaginatedQueryParams, - ): Responses.Paginated; + ): Responses.PaginatedT; // ############################## // View an opportunity (v0.1.0) @@ -74,7 +74,7 @@ interface Opportunities { @path @added(Versions.v0_2) oppId: Types.uuid, - ): Responses.Ok | Responses.NotFound; + ): Responses.OkT | Responses.NotFound; // ############################### // Search opportunities @@ -106,5 +106,5 @@ interface Opportunities { /** Pagination instructions for the results */ pagination?: Pagination.PaginatedBodyParams, - ): Responses.Filtered; + ): Responses.FilteredT; } diff --git a/lib/core/lib/core/sorting.tsp b/lib/core/lib/core/sorting.tsp index 5b76d4bd3..812cdaba9 100644 --- a/lib/core/lib/core/sorting.tsp +++ b/lib/core/lib/core/sorting.tsp @@ -12,7 +12,7 @@ using TypeSpec.JsonSchema; * * @route("/foo/") * @get - * op list(sorting: Sorting.SortQueryParams): Responses.Sorted; + * op list(sorting: Sorting.SortQueryParams): Responses.SortedT; * ``` */ @jsonSchema diff --git a/website/public/openapi/openapi.0.1.0.yaml b/website/public/openapi/openapi.0.1.0.yaml index 37b9d1a86..637b47654 100644 --- a/website/public/openapi/openapi.0.1.0.yaml +++ b/website/public/openapi/openapi.0.1.0.yaml @@ -35,7 +35,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -55,7 +55,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -67,7 +67,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -75,8 +75,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -89,13 +87,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -115,7 +106,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -160,7 +151,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -174,7 +165,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -953,6 +944,16 @@ components: description: Total number of pages example: 5 description: Details about the paginated results + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -973,6 +974,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/website/public/openapi/openapi.0.2.0.yaml b/website/public/openapi/openapi.0.2.0.yaml index 3e0f1b1ac..518f99007 100644 --- a/website/public/openapi/openapi.0.2.0.yaml +++ b/website/public/openapi/openapi.0.2.0.yaml @@ -33,7 +33,7 @@ paths: parameters: [] responses: '201': - description: A 201 response with data + description: A 201 response with typed data content: application/json: schema: @@ -47,7 +47,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 201 response with data + description: A 201 response with typed data '401': description: Access is unauthorized. content: @@ -92,7 +92,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -106,7 +106,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -142,7 +142,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -156,7 +156,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -187,7 +187,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -201,7 +201,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -219,7 +219,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -231,7 +231,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -271,7 +271,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -285,7 +285,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -305,7 +305,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -325,7 +325,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Forms - experimental @@ -343,7 +343,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -357,7 +357,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Forms - experimental @@ -371,7 +371,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -391,7 +391,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -403,7 +403,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -411,8 +411,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -425,13 +423,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -451,7 +442,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -496,7 +487,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -510,7 +501,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -2350,6 +2341,16 @@ components: errors: - field: formA.name message: Name is required + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -2370,6 +2371,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/website/public/openapi/openapi.0.3.0.yaml b/website/public/openapi/openapi.0.3.0.yaml index 486a98e61..246982740 100644 --- a/website/public/openapi/openapi.0.3.0.yaml +++ b/website/public/openapi/openapi.0.3.0.yaml @@ -47,7 +47,7 @@ paths: explode: false responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -55,8 +55,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -69,13 +67,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -95,7 +86,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Applications - experimental @@ -108,7 +99,7 @@ paths: parameters: [] responses: '201': - description: A 201 response with data + description: A 201 response with typed data content: application/json: schema: @@ -122,7 +113,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 201 response with data + description: A 201 response with typed data '401': description: Access is unauthorized. content: @@ -167,7 +158,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -181,7 +172,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -217,7 +208,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -231,7 +222,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -262,7 +253,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -276,7 +267,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Applications - experimental @@ -294,7 +285,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -306,7 +297,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '401': description: Access is unauthorized. content: @@ -346,7 +337,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -360,7 +351,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -380,7 +371,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -400,7 +391,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Forms - experimental @@ -418,7 +409,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -432,7 +423,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data tags: - Forms - experimental @@ -446,7 +437,7 @@ paths: - $ref: '#/components/parameters/CommonGrants.Pagination.PaginatedQueryParams.pageSize' responses: '200': - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items content: application/json: schema: @@ -466,7 +457,7 @@ paths: description: Details about the paginated results allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with a paginated list of items + description: A 200 response with a paginated list of typed items tags: - Opportunities - required @@ -478,7 +469,7 @@ paths: parameters: [] responses: '200': - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter content: application/json: schema: @@ -486,8 +477,6 @@ paths: required: - items - paginationInfo - - status - - message - sortInfo - filterInfo properties: @@ -500,13 +489,6 @@ paths: allOf: - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' description: Details about the paginated results - status: - type: integer - format: int32 - example: 200 - message: - type: string - example: Success sortInfo: allOf: - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' @@ -526,7 +508,7 @@ paths: description: The filters applied to the response items allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A paginated list of items with a filter + description: A paginated list of typed items with a typed filter tags: - Opportunities - optional @@ -571,7 +553,7 @@ paths: $ref: '#/components/schemas/CommonGrants.Types.uuid' responses: '200': - description: A 200 response with data + description: A 200 response with typed data content: application/json: schema: @@ -585,7 +567,7 @@ paths: description: Response data allOf: - $ref: '#/components/schemas/CommonGrants.Responses.Success' - description: A 200 response with data + description: A 200 response with typed data '404': description: The server cannot find the requested resource. content: @@ -2542,6 +2524,16 @@ components: errors: - field: formA.name message: Name is required + CommonGrants.Responses.Created: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 201 response with data CommonGrants.Responses.Error: type: object required: @@ -2562,6 +2554,90 @@ components: items: {} description: List of errors description: A non-2xx response schema + CommonGrants.Responses.Filtered: + type: object + required: + - items + - paginationInfo + - sortInfo + - filterInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + description: The filters applied to the response items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a filter + CommonGrants.Responses.Ok: + type: object + required: + - data + properties: + data: + description: Response data + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with data + CommonGrants.Responses.Paginated: + type: object + required: + - items + - paginationInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A 200 response with a paginated list of items + CommonGrants.Responses.Sorted: + type: object + required: + - items + - paginationInfo + - sortInfo + properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Pagination.PaginatedResultsInfo' + description: Details about the paginated results + sortInfo: + allOf: + - $ref: '#/components/schemas/CommonGrants.Sorting.SortedResultsInfo' + description: The sort order of the items + allOf: + - $ref: '#/components/schemas/CommonGrants.Responses.Success' + description: A paginated list of items with a sort order CommonGrants.Responses.Success: type: object required: diff --git a/website/public/schemas/yaml/Created.yaml b/website/public/schemas/yaml/Created.yaml new file mode 100644 index 000000000..59d5dfd0e --- /dev/null +++ b/website/public/schemas/yaml/Created.yaml @@ -0,0 +1,13 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: Created.yaml +type: object +properties: + data: + description: Response data +required: + - data +allOf: + - $ref: Success.yaml +unevaluatedProperties: + not: {} +description: A 201 response with data diff --git a/website/public/schemas/yaml/Filtered.yaml b/website/public/schemas/yaml/Filtered.yaml new file mode 100644 index 000000000..3debf5369 --- /dev/null +++ b/website/public/schemas/yaml/Filtered.yaml @@ -0,0 +1,38 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: Filtered.yaml +type: object +properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + $ref: PaginatedResultsInfo.yaml + description: Details about the paginated results + sortInfo: + $ref: SortedResultsInfo.yaml + description: The sort order of the items + filterInfo: + type: object + properties: + filters: {} + errors: + type: array + items: + type: string + description: Non-fatal errors that occurred during filtering + required: + - filters + unevaluatedProperties: + not: {} + description: The filters applied to the response items +required: + - items + - paginationInfo + - sortInfo + - filterInfo +allOf: + - $ref: Success.yaml +unevaluatedProperties: + not: {} +description: A paginated list of items with a filter diff --git a/website/public/schemas/yaml/Ok.yaml b/website/public/schemas/yaml/Ok.yaml new file mode 100644 index 000000000..a1c12c2f7 --- /dev/null +++ b/website/public/schemas/yaml/Ok.yaml @@ -0,0 +1,13 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: Ok.yaml +type: object +properties: + data: + description: Response data +required: + - data +allOf: + - $ref: Success.yaml +unevaluatedProperties: + not: {} +description: A 200 response with data diff --git a/website/public/schemas/yaml/Paginated.yaml b/website/public/schemas/yaml/Paginated.yaml new file mode 100644 index 000000000..7ccfc8045 --- /dev/null +++ b/website/public/schemas/yaml/Paginated.yaml @@ -0,0 +1,19 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: Paginated.yaml +type: object +properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + $ref: PaginatedResultsInfo.yaml + description: Details about the paginated results +required: + - items + - paginationInfo +allOf: + - $ref: Success.yaml +unevaluatedProperties: + not: {} +description: A 200 response with a paginated list of items diff --git a/website/public/schemas/yaml/Sorted.yaml b/website/public/schemas/yaml/Sorted.yaml new file mode 100644 index 000000000..2640c590f --- /dev/null +++ b/website/public/schemas/yaml/Sorted.yaml @@ -0,0 +1,23 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: Sorted.yaml +type: object +properties: + items: + type: array + items: {} + description: Items from the current page + paginationInfo: + $ref: PaginatedResultsInfo.yaml + description: Details about the paginated results + sortInfo: + $ref: SortedResultsInfo.yaml + description: The sort order of the items +required: + - items + - paginationInfo + - sortInfo +allOf: + - $ref: Success.yaml +unevaluatedProperties: + not: {} +description: A paginated list of items with a sort order diff --git a/website/public/schemas/yaml/Success.yaml b/website/public/schemas/yaml/Success.yaml index f6fafd867..d512fd011 100644 --- a/website/public/schemas/yaml/Success.yaml +++ b/website/public/schemas/yaml/Success.yaml @@ -15,5 +15,3 @@ properties: required: - status - message -unevaluatedProperties: - not: {} diff --git a/website/src/content/docs/protocol/responses/error.mdx b/website/src/content/docs/protocol/responses/error.mdx index e050a5e0c..fc31e765a 100644 --- a/website/src/content/docs/protocol/responses/error.mdx +++ b/website/src/content/docs/protocol/responses/error.mdx @@ -85,7 +85,7 @@ using CommonGrants.Responses; @summary("Get test") @doc("Get a test model") @get -op getTest(): Ok | Error; +op getTest(): OkT | Error; ``` ### Changelog diff --git a/website/src/content/docs/protocol/responses/filtered.mdx b/website/src/content/docs/protocol/responses/filtered.mdx index a4e3944d1..387fea1b6 100644 --- a/website/src/content/docs/protocol/responses/filtered.mdx +++ b/website/src/content/docs/protocol/responses/filtered.mdx @@ -46,42 +46,13 @@ filtered: } } jsonSchema: - code: | - $schema: https://json-schema.org/draft/2020-12/schema - $id: Filtered.yaml - type: object - properties: - items: - type: array - description: Items from the current page - paginationInfo: - $ref: PaginatedResultsInfo.yaml - sortInfo: - $ref: SortedResultsInfo.yaml - filterInfo: - type: object - description: The filters applied to the response items - properties: - filters: - type: object - description: The filters applied to the response items - errors: - type: array - items: - type: string - description: Non-fatal errors that occurred during filtering - allOf: - - $ref: Success.yaml - required: - - items - - paginationInfo - - sortInfo - - filterInfo + file: + path: "website/public/schemas/yaml/Filtered.yaml" typeSpec: file: path: "lib/core/lib/core/responses/success.tsp" - startLine: 140 - endLine: 153 + startLine: 177 + endLine: 198 python: file: path: "lib/python-sdk/common_grants_sdk/schemas/pydantic/responses/success.py" @@ -121,3 +92,34 @@ A 200 response with a paginated list of filtered items. python={frontmatter.filtered.python} typescript={frontmatter.filtered.typescript} /> + +### Usage + +Use the `FilteredT` template to define a 200 response with a paginated list of filtered, typed items within an API operation: + +```typespec +import "@common-grants/core"; +import "@typespec/http"; + +using TypeSpec.Http; +using CommonGrants.Pagination; +using CommonGrants.Responses; + +model TestModel { + id: string; + name: string; +} + +model TestFilter extends Record { + lastModifiedAt: Filters.DateComparisonFilter; +} + +@summary("Search test models") +@doc("Get a paginated list of test models matching a filter") +@post +op searchTest(...PaginatedBodyParams): FilteredT; +``` + +### Changelog + + diff --git a/website/src/content/docs/protocol/responses/paginated.mdx b/website/src/content/docs/protocol/responses/paginated.mdx index 845287b9c..537707e35 100644 --- a/website/src/content/docs/protocol/responses/paginated.mdx +++ b/website/src/content/docs/protocol/responses/paginated.mdx @@ -27,28 +27,13 @@ paginated: } } jsonSchema: - code: | - $schema: https://json-schema.org/draft/2020-12/schema - $id: Paginated.yaml - type: object - properties: - items: - type: array - description: Items from the current page - paginationInfo: - $ref: PaginatedResultsInfo.yaml - allOf: - - $ref: Success.yaml - required: - - status - - message - - items - - paginationInfo + file: + path: "website/public/schemas/yaml/Paginated.yaml" typeSpec: file: path: "lib/core/lib/core/responses/success.tsp" - startLine: 70 - endLine: 82 + startLine: 72 + endLine: 90 python: file: path: "lib/python-sdk/common_grants_sdk/schemas/pydantic/responses/success.py" @@ -89,7 +74,7 @@ A 200 response with a paginated list of items. ### Usage -Here's an example of how to use the `Paginated` response within a an API operation: +Use the `PaginatedT` template to define a 200 response with a paginated list of typed items within an API operation: ```typespec import "@common-grants/core"; @@ -107,5 +92,9 @@ model TestModel { @summary("List test models") @doc("Get a paginated list of test models") @get -op listTest(...PaginatedQueryParams): Paginated; +op listTest(...PaginatedQueryParams): PaginatedT; ``` + +### Changelog + + diff --git a/website/src/content/docs/protocol/responses/sorted.mdx b/website/src/content/docs/protocol/responses/sorted.mdx index c53ed1902..640467a18 100644 --- a/website/src/content/docs/protocol/responses/sorted.mdx +++ b/website/src/content/docs/protocol/responses/sorted.mdx @@ -31,29 +31,13 @@ sorted: } } jsonSchema: - code: | - $schema: https://json-schema.org/draft/2020-12/schema - $id: Sorted.yaml - type: object - properties: - items: - type: array - description: Items from the current page - paginationInfo: - $ref: PaginatedResultsInfo.yaml - sortInfo: - $ref: SortedResultsInfo.yaml - allOf: - - $ref: Success.yaml - required: - - items - - paginationInfo - - sortInfo + file: + path: "website/public/schemas/yaml/Sorted.yaml" typeSpec: file: path: "lib/core/lib/core/responses/success.tsp" - startLine: 104 - endLine: 112 + startLine: 125 + endLine: 141 python: file: path: "lib/python-sdk/common_grants_sdk/schemas/pydantic/responses/success.py" @@ -95,7 +79,7 @@ A 200 response with a paginated list of sorted items. ### Usage -Here's an example of how to use the `Sorted` response within a an API operation: +Use the `SortedT` template to define a 200 response with a paginated list of sorted, typed items within an API operation: ```typespec import "@common-grants/core"; @@ -113,5 +97,9 @@ model TestModel { @summary("List test models") @doc("Get a paginated list of test models") @get -op listTest(...PaginatedQueryParams): Sorted; +op listTest(...PaginatedQueryParams): SortedT; ``` + +### Changelog + + diff --git a/website/src/content/docs/protocol/responses/success.mdx b/website/src/content/docs/protocol/responses/success.mdx index b24f741a5..1a6fefa8c 100644 --- a/website/src/content/docs/protocol/responses/success.mdx +++ b/website/src/content/docs/protocol/responses/success.mdx @@ -15,32 +15,32 @@ ok: } } jsonSchema: + file: + path: "website/public/schemas/yaml/Ok.yaml" + typeSpec: + file: + path: "lib/core/lib/core/responses/success.tsp" + startLine: 31 + endLine: 36 +created: + example: code: | - $schema: https://json-schema.org/draft/2020-12/schema - $id: Ok.yaml - type: object - properties: - status: - type: integer - minimum: 200 - default: 200 - description: The HTTP status code - message: - type: string - default: "Success" - description: The message to return - data: - type: object - description: The data to return - required: - - status - - message - - data + { + "status": 201, + "message": "Created", + "data": { + "id": "123", + "name": "Test 1" + } + } + jsonSchema: + file: + path: "website/public/schemas/yaml/Created.yaml" typeSpec: file: path: "lib/core/lib/core/responses/success.tsp" - startLine: 40 - endLine: 48 + startLine: 239 + endLine: 244 success: example: file: @@ -51,8 +51,8 @@ success: typeSpec: file: path: "lib/core/lib/core/responses/success.tsp" - startLine: 11 - endLine: 19 + startLine: 14 + endLine: 21 python: file: path: "lib/python-sdk/common_grants_sdk/schemas/pydantic/responses/success.py" @@ -117,7 +117,7 @@ A 200 response with data. ### Usage -Here's an example of how to use the `Ok` response within a an API operation: +Use the `OkT` template to define a 200 response with typed data within an API operation: ```typespec import "@common-grants/core"; @@ -134,5 +134,55 @@ model TestModel { @summary("Get test") @doc("Get a test model") @get -op getTest(): Ok; +op getTest(): OkT; ``` + +### Changelog + + + +## Created + +A 201 response with data. + +### Table + +| Parameter | Type | Description | +| --------- | ------------------------------------------ | --------------------- | +| status | [integer](/protocol/types/numeric#integer) | The HTTP status code | +| message | [string](/protocol/types/string#string) | The message to return | +| data | any | The data to return | + +### Formats + + + +### Usage + +Use the `CreatedT` template to define a 201 response with typed data within an API operation: + +```typespec +import "@common-grants/core"; +import "@typespec/http"; + +using TypeSpec.Http; +using CommonGrants.Responses; + +model TestModel { + id: string; + name: string; +} + +@summary("Create test") +@doc("Create a test model") +@post +op createTest(@body body: TestModel): CreatedT; +``` + +### Changelog + +