From 088fde5c3c15b3b59b88cfeb3ae3480a9c93bc41 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Fri, 27 Oct 2023 01:00:34 +0200 Subject: [PATCH] OpenAPI: Auto-generated documentation (#1371) * Generate documentation for JSON:API endpoints * Generate documentation for JSON:API resource types and attributes * Rename path property, which is actually a directory * Add 403 status when client-generated IDs are forbidden (default) * Update documentation --- docs/usage/openapi.md | 25 +- .../JsonApiOperationIdSelector.cs | 2 +- .../ServiceCollectionExtensions.cs | 1 + .../EndpointOrderingFilter.cs | 4 +- .../JsonApiOperationDocumentationFilter.cs | 408 +++++++++ .../ResourceFieldObjectSchemaBuilder.cs | 10 +- .../ResourceObjectDocumentationReader.cs | 87 ++ .../ResourceObjectSchemaGenerator.cs | 11 +- .../LegacyClient/swagger.g.json | 790 +++++++++++++----- .../CamelCase/swagger.g.json | 282 +++++-- .../KebabCase/swagger.g.json | 282 +++++-- .../PascalCase/swagger.g.json | 282 +++++-- .../ModelStateValidationOff/swagger.g.json | 368 +++++--- .../ModelStateValidationOn/swagger.g.json | 368 +++++--- .../ModelStateValidationOff/swagger.g.json | 484 +++++++---- .../ModelStateValidationOn/swagger.g.json | 484 +++++++---- .../DocComments/DocCommentsDbContext.cs | 30 + .../DocComments/DocCommentsStartup.cs | 41 + .../DocComments/DocCommentsTests.cs | 499 +++++++++++ test/OpenApiTests/DocComments/Elevator.cs | 26 + test/OpenApiTests/DocComments/Skyscraper.cs | 33 + test/OpenApiTests/DocComments/Space.cs | 31 + test/OpenApiTests/DocComments/SpaceKind.cs | 15 + .../LegacyOpenApiIntegration/Airline.cs | 3 + .../LegacyOpenApiIntegration/Airplane.cs | 3 + .../LegacyOpenApiIntegrationTests.cs | 2 +- .../LegacyOpenApiIntegration/swagger.json | 790 +++++++++++++----- .../CamelCase/CamelCaseTests.cs | 2 +- .../KebabCase/KebabCaseTests.cs | 2 +- .../PascalCase/PascalCaseTests.cs | 2 +- test/OpenApiTests/OpenApiStartup.cs | 10 +- test/OpenApiTests/OpenApiTestContext.cs | 6 +- test/OpenApiTests/OpenApiTests.csproj | 2 + .../NullabilityTests.cs | 2 +- .../NullabilityTests.cs | 2 +- .../NullabilityTests.cs | 2 +- .../NullabilityTests.cs | 2 +- .../JsonElementAssertionExtensions.cs | 5 + 38 files changed, 4217 insertions(+), 1181 deletions(-) create mode 100644 src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiOperationDocumentationFilter.cs create mode 100644 src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectDocumentationReader.cs create mode 100644 test/OpenApiTests/DocComments/DocCommentsDbContext.cs create mode 100644 test/OpenApiTests/DocComments/DocCommentsStartup.cs create mode 100644 test/OpenApiTests/DocComments/DocCommentsTests.cs create mode 100644 test/OpenApiTests/DocComments/Elevator.cs create mode 100644 test/OpenApiTests/DocComments/Skyscraper.cs create mode 100644 test/OpenApiTests/DocComments/Space.cs create mode 100644 test/OpenApiTests/DocComments/SpaceKind.cs diff --git a/docs/usage/openapi.md b/docs/usage/openapi.md index fb37a60954..1419a6ba43 100644 --- a/docs/usage/openapi.md +++ b/docs/usage/openapi.md @@ -1,6 +1,8 @@ # OpenAPI -JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints. This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages. The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). +JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints. +This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages. +The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). ## Getting started @@ -35,10 +37,29 @@ By default, the OpenAPI specification will be available at `http://localhost:/swagger`. + +### Triple-slash comments + +Documentation for JSON:API endpoints is provided out of the box, which shows in SwaggerUI and through IDE IntelliSense in auto-generated clients. +To also get documentation for your resource classes and their properties, add the following to your project file. +The `NoWarn` line is optional, which suppresses build warnings for undocumented types and members. + +```xml + + True + $(NoWarn);1591 + +``` + +You can combine this with the documentation that Swagger itself supports, by enabling it as described [here](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments). +This adds documentation for additional types, such as triple-slash comments on enums used in your resource models. diff --git a/src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs b/src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs index a32d781f5f..507cd26e59 100644 --- a/src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs +++ b/src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs @@ -116,7 +116,7 @@ private string ApplyTemplate(string operationIdTemplate, ResourceType resourceTy string relationshipName = operationIdTemplate.Contains("[RelationshipName]") ? endpoint.RelativePath.Split("/").Last() : string.Empty; // @formatter:wrap_chained_method_calls chop_always - // @formatter:wrap_before_first_method_call true true + // @formatter:wrap_before_first_method_call true string pascalCaseOperationId = operationIdTemplate .Replace("[Method]", method) diff --git a/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs b/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs index 03469f3e40..2cec6680e2 100644 --- a/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs +++ b/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs @@ -70,6 +70,7 @@ private static void AddSwaggerGenerator(IServiceScope scope, IServiceCollection SetOperationInfo(swaggerGenOptions, controllerResourceMapping, namingPolicy); SetSchemaIdSelector(swaggerGenOptions, resourceGraph, namingPolicy); swaggerGenOptions.DocumentFilter(); + swaggerGenOptions.OperationFilter(); setupSwaggerGenAction?.Invoke(swaggerGenOptions); }); diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/EndpointOrderingFilter.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/EndpointOrderingFilter.cs index 7740d2973b..c16cbe28d9 100644 --- a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/EndpointOrderingFilter.cs +++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/EndpointOrderingFilter.cs @@ -16,12 +16,12 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context) ArgumentGuard.NotNull(swaggerDoc); ArgumentGuard.NotNull(context); - List> orderedEndpoints = swaggerDoc.Paths.OrderBy(GetPrimaryResourcePublicName) + List> endpointsInOrder = swaggerDoc.Paths.OrderBy(GetPrimaryResourcePublicName) .ThenBy(GetRelationshipName).ThenBy(IsSecondaryEndpoint).ToList(); swaggerDoc.Paths.Clear(); - foreach ((string url, OpenApiPathItem path) in orderedEndpoints) + foreach ((string url, OpenApiPathItem path) in endpointsInOrder) { swaggerDoc.Paths.Add(url, path); } diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiOperationDocumentationFilter.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiOperationDocumentationFilter.cs new file mode 100644 index 0000000000..a5abe45263 --- /dev/null +++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiOperationDocumentationFilter.cs @@ -0,0 +1,408 @@ +using System.Net; +using Humanizer; +using JetBrains.Annotations; +using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Controllers; +using JsonApiDotNetCore.Middleware; +using JsonApiDotNetCore.Resources; +using JsonApiDotNetCore.Resources.Annotations; +using Microsoft.AspNetCore.Mvc.ApiExplorer; +using Microsoft.OpenApi.Models; +using Swashbuckle.AspNetCore.SwaggerGen; + +namespace JsonApiDotNetCore.OpenApi.SwaggerComponents; + +[UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)] +internal sealed class JsonApiOperationDocumentationFilter : IOperationFilter +{ + private const string GetPrimaryName = nameof(BaseJsonApiController, int>.GetAsync); + private const string GetSecondaryName = nameof(BaseJsonApiController, int>.GetSecondaryAsync); + private const string GetRelationshipName = nameof(BaseJsonApiController, int>.GetRelationshipAsync); + private const string PostResourceName = nameof(BaseJsonApiController, int>.PostAsync); + private const string PostRelationshipName = nameof(BaseJsonApiController, int>.PostRelationshipAsync); + private const string PatchResourceName = nameof(BaseJsonApiController, int>.PatchAsync); + private const string PatchRelationshipName = nameof(BaseJsonApiController, int>.PatchRelationshipAsync); + private const string DeleteResourceName = nameof(BaseJsonApiController, int>.DeleteAsync); + private const string DeleteRelationshipName = nameof(BaseJsonApiController, int>.DeleteRelationshipAsync); + + private const string TextCompareETag = + "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."; + + private const string TextCompletedSuccessfully = "The operation completed successfully."; + private const string TextRequestBodyMissingOrMalformed = "The request body is missing or malformed."; + private const string TextRequestBodyIncompatibleType = "A resource type in the request body is incompatible."; + private const string TextRequestBodyIncompatibleIdOrType = "A resource type or identifier in the request body is incompatible."; + private const string TextRequestBodyValidationFailed = "Validation of the request body failed."; + private const string TextRequestBodyClientId = "Client-generated IDs cannot be used at this endpoint."; + + private readonly IJsonApiOptions _options; + private readonly IControllerResourceMapping _controllerResourceMapping; + private readonly ResourceFieldValidationMetadataProvider _resourceFieldValidationMetadataProvider; + + public JsonApiOperationDocumentationFilter(IJsonApiOptions options, IControllerResourceMapping controllerResourceMapping, + ResourceFieldValidationMetadataProvider resourceFieldValidationMetadataProvider) + { + ArgumentGuard.NotNull(options); + ArgumentGuard.NotNull(controllerResourceMapping); + ArgumentGuard.NotNull(resourceFieldValidationMetadataProvider); + + _options = options; + _controllerResourceMapping = controllerResourceMapping; + _resourceFieldValidationMetadataProvider = resourceFieldValidationMetadataProvider; + } + + public void Apply(OpenApiOperation operation, OperationFilterContext context) + { + ArgumentGuard.NotNull(operation); + ArgumentGuard.NotNull(context); + + bool hasHeadVerb = context.ApiDescription.HttpMethod == "HEAD"; + + if (hasHeadVerb) + { + operation.Responses.Clear(); + } + + ResourceType? resourceType = + _controllerResourceMapping.GetResourceTypeForController(context.ApiDescription.ActionDescriptor.GetActionMethod().ReflectedType); + + if (resourceType != null) + { + string actionName = context.MethodInfo.Name; + + switch (actionName) + { + case GetPrimaryName or PostResourceName or PatchResourceName or DeleteResourceName: + { + switch (actionName) + { + case GetPrimaryName: + { + ApplyGetPrimary(operation, resourceType, hasHeadVerb); + break; + } + case PostResourceName: + { + ApplyPostResource(operation, resourceType); + break; + } + case PatchResourceName: + { + ApplyPatchResource(operation, resourceType); + break; + } + case DeleteResourceName: + { + ApplyDeleteResource(operation, resourceType); + break; + } + } + + break; + } + case GetSecondaryName or GetRelationshipName or PostRelationshipName or PatchRelationshipName or DeleteRelationshipName: + { + RelationshipAttribute relationship = GetRelationshipFromRoute(context.ApiDescription, resourceType); + + switch (actionName) + { + case GetSecondaryName: + { + ApplyGetSecondary(operation, relationship, hasHeadVerb); + break; + } + case GetRelationshipName: + { + ApplyGetRelationship(operation, relationship, hasHeadVerb); + break; + } + case PostRelationshipName: + { + ApplyPostRelationship(operation, relationship); + break; + } + case PatchRelationshipName: + { + ApplyPatchRelationship(operation, relationship); + break; + } + case DeleteRelationshipName: + { + ApplyDeleteRelationship(operation, relationship); + break; + } + } + + break; + } + } + } + } + + private static void ApplyGetPrimary(OpenApiOperation operation, ResourceType resourceType, bool hasHeadVerb) + { + if (operation.Parameters.Count == 0) + { + if (hasHeadVerb) + { + SetOperationSummary(operation, $"Retrieves a collection of {resourceType} without returning them."); + SetOperationRemarks(operation, TextCompareETag); + SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully); + } + else + { + SetOperationSummary(operation, $"Retrieves a collection of {resourceType}."); + + SetResponseDescription(operation.Responses, HttpStatusCode.OK, + $"Successfully returns the found {resourceType}, or an empty array if none were found."); + } + } + else if (operation.Parameters.Count == 1) + { + string singularName = resourceType.PublicName.Singularize(); + + if (hasHeadVerb) + { + SetOperationSummary(operation, $"Retrieves an individual {singularName} by its identifier without returning it."); + SetOperationRemarks(operation, TextCompareETag); + SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully); + } + else + { + SetOperationSummary(operation, $"Retrieves an individual {singularName} by its identifier."); + SetResponseDescription(operation.Responses, HttpStatusCode.OK, $"Successfully returns the found {singularName}."); + } + + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularName} to retrieve."); + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularName} does not exist."); + } + } + + private void ApplyPostResource(OpenApiOperation operation, ResourceType resourceType) + { + string singularName = resourceType.PublicName.Singularize(); + + SetOperationSummary(operation, $"Creates a new {singularName}."); + SetRequestBodyDescription(operation.RequestBody, $"The attributes and relationships of the {singularName} to create."); + + SetResponseDescription(operation.Responses, HttpStatusCode.Created, + $"The {singularName} was successfully created, which resulted in additional changes. The newly created {singularName} is returned."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, + $"The {singularName} was successfully created, which did not result in additional changes."); + + SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextRequestBodyMissingOrMalformed); + SetResponseDescription(operation.Responses, HttpStatusCode.Conflict, TextRequestBodyIncompatibleType); + SetResponseDescription(operation.Responses, HttpStatusCode.UnprocessableEntity, TextRequestBodyValidationFailed); + + ClientIdGenerationMode clientIdGeneration = resourceType.ClientIdGeneration ?? _options.ClientIdGeneration; + + if (clientIdGeneration == ClientIdGenerationMode.Forbidden) + { + SetResponseDescription(operation.Responses, HttpStatusCode.Forbidden, TextRequestBodyClientId); + } + } + + private void ApplyPatchResource(OpenApiOperation operation, ResourceType resourceType) + { + string singularName = resourceType.PublicName.Singularize(); + + SetOperationSummary(operation, $"Updates an existing {singularName}."); + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularName} to update."); + + SetRequestBodyDescription(operation.RequestBody, + $"The attributes and relationships of the {singularName} to update. Omitted fields are left unchanged."); + + SetResponseDescription(operation.Responses, HttpStatusCode.OK, + $"The {singularName} was successfully updated, which resulted in additional changes. The updated {singularName} is returned."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, + $"The {singularName} was successfully updated, which did not result in additional changes."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularName} or a related resource does not exist."); + SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextRequestBodyMissingOrMalformed); + SetResponseDescription(operation.Responses, HttpStatusCode.Conflict, TextRequestBodyIncompatibleIdOrType); + SetResponseDescription(operation.Responses, HttpStatusCode.UnprocessableEntity, TextRequestBodyValidationFailed); + } + + private void ApplyDeleteResource(OpenApiOperation operation, ResourceType resourceType) + { + string singularName = resourceType.PublicName.Singularize(); + + SetOperationSummary(operation, $"Deletes an existing {singularName} by its identifier."); + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularName} to delete."); + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, $"The {singularName} was successfully deleted."); + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularName} does not exist."); + } + + private static void ApplyGetSecondary(OpenApiOperation operation, RelationshipAttribute relationship, bool hasHeadVerb) + { + string singularLeftName = relationship.LeftType.PublicName.Singularize(); + string rightName = relationship is HasOneAttribute ? relationship.RightType.PublicName.Singularize() : relationship.RightType.PublicName; + + if (hasHeadVerb) + { + SetOperationSummary(operation, + relationship is HasOneAttribute + ? $"Retrieves the related {rightName} of an individual {singularLeftName}'s {relationship} relationship without returning it." + : $"Retrieves the related {rightName} of an individual {singularLeftName}'s {relationship} relationship without returning them."); + + SetOperationRemarks(operation, TextCompareETag); + SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully); + } + else + { + SetOperationSummary(operation, $"Retrieves the related {rightName} of an individual {singularLeftName}'s {relationship} relationship."); + + SetResponseDescription(operation.Responses, HttpStatusCode.OK, + relationship is HasOneAttribute + ? $"Successfully returns the found {rightName}, or null if it was not found." + : $"Successfully returns the found {rightName}, or an empty array if none were found."); + } + + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {rightName} to retrieve."); + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist."); + } + + private static void ApplyGetRelationship(OpenApiOperation operation, RelationshipAttribute relationship, bool hasHeadVerb) + { + string singularLeftName = relationship.LeftType.PublicName.Singularize(); + string singularRightName = relationship.RightType.PublicName.Singularize(); + string ident = relationship is HasOneAttribute ? "identity" : "identities"; + + if (hasHeadVerb) + { + SetOperationSummary(operation, + relationship is HasOneAttribute + ? $"Retrieves the related {singularRightName} {ident} of an individual {singularLeftName}'s {relationship} relationship without returning it." + : $"Retrieves the related {singularRightName} {ident} of an individual {singularLeftName}'s {relationship} relationship without returning them."); + + SetOperationRemarks(operation, TextCompareETag); + SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully); + } + else + { + SetOperationSummary(operation, + $"Retrieves the related {singularRightName} {ident} of an individual {singularLeftName}'s {relationship} relationship."); + + SetResponseDescription(operation.Responses, HttpStatusCode.OK, + relationship is HasOneAttribute + ? $"Successfully returns the found {singularRightName} {ident}, or null if it was not found." + : $"Successfully returns the found {singularRightName} {ident}, or an empty array if none were found."); + } + + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {singularRightName} {ident} to retrieve."); + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist."); + } + + private void ApplyPostRelationship(OpenApiOperation operation, RelationshipAttribute relationship) + { + string singularLeftName = relationship.LeftType.PublicName.Singularize(); + string rightName = relationship.RightType.PublicName; + + SetOperationSummary(operation, $"Adds existing {rightName} to the {relationship} relationship of an individual {singularLeftName}."); + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} to add {rightName} to."); + SetRequestBodyDescription(operation.RequestBody, $"The identities of the {rightName} to add to the {relationship} relationship."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, + $"The {rightName} were successfully added, which did not result in additional changes."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist."); + SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextRequestBodyMissingOrMalformed); + SetResponseDescription(operation.Responses, HttpStatusCode.Conflict, TextRequestBodyIncompatibleType); + } + + private void ApplyPatchRelationship(OpenApiOperation operation, RelationshipAttribute relationship) + { + bool isOptional = _resourceFieldValidationMetadataProvider.IsNullable(relationship); + string singularLeftName = relationship.LeftType.PublicName.Singularize(); + string rightName = relationship is HasOneAttribute ? relationship.RightType.PublicName.Singularize() : relationship.RightType.PublicName; + + SetOperationSummary(operation, + relationship is HasOneAttribute + ? isOptional + ? $"Clears or assigns an existing {rightName} to the {relationship} relationship of an individual {singularLeftName}." + : $"Assigns an existing {rightName} to the {relationship} relationship of an individual {singularLeftName}." + : $"Assigns existing {rightName} to the {relationship} relationship of an individual {singularLeftName}."); + + SetParameterDescription(operation.Parameters[0], + isOptional + ? $"The identifier of the {singularLeftName} whose {relationship} relationship to assign or clear." + : $"The identifier of the {singularLeftName} whose {relationship} relationship to assign."); + + SetRequestBodyDescription(operation.RequestBody, + relationship is HasOneAttribute + ? isOptional + ? $"The identity of the {rightName} to assign to the {relationship} relationship, or null to clear the relationship." + : $"The identity of the {rightName} to assign to the {relationship} relationship." + : $"The identities of the {rightName} to assign to the {relationship} relationship, or an empty array to clear the relationship."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, + $"The {relationship} relationship was successfully updated, which did not result in additional changes."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist."); + SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextRequestBodyMissingOrMalformed); + SetResponseDescription(operation.Responses, HttpStatusCode.Conflict, TextRequestBodyIncompatibleType); + } + + private void ApplyDeleteRelationship(OpenApiOperation operation, RelationshipAttribute relationship) + { + string singularLeftName = relationship.LeftType.PublicName.Singularize(); + string rightName = relationship.RightType.PublicName; + + SetOperationSummary(operation, $"Removes existing {rightName} from the {relationship} relationship of an individual {singularLeftName}."); + SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} to remove {rightName} from."); + SetRequestBodyDescription(operation.RequestBody, $"The identities of the {rightName} to remove from the {relationship} relationship."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NoContent, + $"The {rightName} were successfully removed, which did not result in additional changes."); + + SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist."); + SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextRequestBodyMissingOrMalformed); + SetResponseDescription(operation.Responses, HttpStatusCode.Conflict, TextRequestBodyIncompatibleType); + } + + private static RelationshipAttribute GetRelationshipFromRoute(ApiDescription apiDescription, ResourceType resourceType) + { + if (apiDescription.RelativePath == null) + { + throw new UnreachableCodeException(); + } + + string relationshipName = apiDescription.RelativePath.Split('/').Last(); + return resourceType.GetRelationshipByPublicName(relationshipName); + } + + private static void SetOperationSummary(OpenApiOperation operation, string description) + { + operation.Summary = XmlCommentsTextHelper.Humanize(description); + } + + private static void SetOperationRemarks(OpenApiOperation operation, string description) + { + operation.Description = XmlCommentsTextHelper.Humanize(description); + } + + private static void SetParameterDescription(OpenApiParameter parameter, string description) + { + parameter.Description = XmlCommentsTextHelper.Humanize(description); + } + + private static void SetRequestBodyDescription(OpenApiRequestBody requestBody, string description) + { + requestBody.Description = XmlCommentsTextHelper.Humanize(description); + } + + private static void SetResponseDescription(OpenApiResponses responses, HttpStatusCode statusCode, string description) + { + string responseCode = ((int)statusCode).ToString(); + + if (!responses.TryGetValue(responseCode, out OpenApiResponse? response)) + { + response = new OpenApiResponse(); + responses.Add(responseCode, response); + } + + response.Description = XmlCommentsTextHelper.Humanize(description); + } +} diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs index 84b473990f..a3691f3b58 100644 --- a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs +++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs @@ -39,6 +39,7 @@ internal sealed class ResourceFieldObjectSchemaBuilder private readonly IDictionary _schemasForResourceFields; private readonly ResourceFieldValidationMetadataProvider _resourceFieldValidationMetadataProvider; private readonly RelationshipTypeFactory _relationshipTypeFactory; + private readonly ResourceObjectDocumentationReader _resourceObjectDocumentationReader; public ResourceFieldObjectSchemaBuilder(ResourceTypeInfo resourceTypeInfo, ISchemaRepositoryAccessor schemaRepositoryAccessor, SchemaGenerator defaultSchemaGenerator, ResourceTypeSchemaGenerator resourceTypeSchemaGenerator, JsonNamingPolicy? namingPolicy, @@ -59,6 +60,7 @@ public ResourceFieldObjectSchemaBuilder(ResourceTypeInfo resourceTypeInfo, ISche _nullableReferenceSchemaGenerator = new NullableReferenceSchemaGenerator(schemaRepositoryAccessor, namingPolicy); _relationshipTypeFactory = new RelationshipTypeFactory(resourceFieldValidationMetadataProvider); _schemasForResourceFields = GetFieldSchemas(); + _resourceObjectDocumentationReader = new ResourceObjectDocumentationReader(); } private IDictionary GetFieldSchemas() @@ -92,6 +94,8 @@ public void SetMembersOfAttributesObject(OpenApiSchema fullSchemaForAttributesOb { fullSchemaForAttributesObject.Required.Add(matchingAttribute.PublicName); } + + resourceFieldSchema.Description = _resourceObjectDocumentationReader.GetDocumentationForAttribute(matchingAttribute); } } } @@ -131,7 +135,7 @@ public void SetMembersOfRelationshipsObject(OpenApiSchema fullSchemaForRelations { ArgumentGuard.NotNull(fullSchemaForRelationshipsObject); - foreach (string fieldName in _schemasForResourceFields.Keys) + foreach ((string fieldName, OpenApiSchema resourceFieldSchema) in _schemasForResourceFields) { RelationshipAttribute? matchingRelationship = _resourceTypeInfo.ResourceType.FindRelationshipByPublicName(fieldName); @@ -139,6 +143,10 @@ public void SetMembersOfRelationshipsObject(OpenApiSchema fullSchemaForRelations { EnsureResourceIdentifierObjectSchemaExists(matchingRelationship); AddRelationshipSchemaToResourceObject(matchingRelationship, fullSchemaForRelationshipsObject); + + // This currently has no effect because $ref cannot be combined with other elements in OAS 3.0. + // This can be worked around by using the allOf operator. See https://github.com/OAI/OpenAPI-Specification/issues/1514. + resourceFieldSchema.Description = _resourceObjectDocumentationReader.GetDocumentationForRelationship(matchingRelationship); } } } diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectDocumentationReader.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectDocumentationReader.cs new file mode 100644 index 0000000000..fa50f98436 --- /dev/null +++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectDocumentationReader.cs @@ -0,0 +1,87 @@ +using System.Collections.Concurrent; +using System.Reflection; +using System.Xml.XPath; +using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Resources.Annotations; +using Swashbuckle.AspNetCore.SwaggerGen; + +namespace JsonApiDotNetCore.OpenApi.SwaggerComponents; + +internal sealed class ResourceObjectDocumentationReader +{ + private static readonly ConcurrentDictionary NavigatorsByAssemblyPath = new(); + + public string? GetDocumentationForType(ResourceType resourceType) + { + ArgumentGuard.NotNull(resourceType); + + XPathNavigator? navigator = GetNavigator(resourceType.ClrType.Assembly); + + if (navigator != null) + { + string typeMemberName = XmlCommentsNodeNameHelper.GetMemberNameForType(resourceType.ClrType); + return GetSummary(navigator, typeMemberName); + } + + return null; + } + + public string? GetDocumentationForAttribute(AttrAttribute attribute) + { + ArgumentGuard.NotNull(attribute); + + XPathNavigator? navigator = GetNavigator(attribute.Type.ClrType.Assembly); + + if (navigator != null) + { + string propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(attribute.Property); + return GetSummary(navigator, propertyMemberName); + } + + return null; + } + + public string? GetDocumentationForRelationship(RelationshipAttribute relationship) + { + ArgumentGuard.NotNull(relationship); + + XPathNavigator? navigator = GetNavigator(relationship.Type.ClrType.Assembly); + + if (navigator != null) + { + string propertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(relationship.Property); + return GetSummary(navigator, propertyMemberName); + } + + return null; + } + + private static XPathNavigator? GetNavigator(Assembly assembly) + { + string assemblyPath = assembly.Location; + + if (!string.IsNullOrEmpty(assemblyPath)) + { + return NavigatorsByAssemblyPath.GetOrAdd(assemblyPath, path => + { + string documentationPath = Path.ChangeExtension(path, ".xml"); + + if (File.Exists(documentationPath)) + { + var document = new XPathDocument(documentationPath); + return document.CreateNavigator(); + } + + return null; + }); + } + + return null; + } + + private string? GetSummary(XPathNavigator navigator, string memberName) + { + XPathNavigator? summaryNode = navigator.SelectSingleNode($"/doc/members/member[@name='{memberName}']/summary"); + return summaryNode != null ? XmlCommentsTextHelper.Humanize(summaryNode.InnerXml) : null; + } +} diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectSchemaGenerator.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectSchemaGenerator.cs index 42fd662719..4977b61025 100644 --- a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectSchemaGenerator.cs +++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectSchemaGenerator.cs @@ -23,6 +23,7 @@ internal sealed class ResourceObjectSchemaGenerator private readonly ISchemaRepositoryAccessor _schemaRepositoryAccessor; private readonly ResourceTypeSchemaGenerator _resourceTypeSchemaGenerator; private readonly Func _resourceFieldObjectSchemaBuilderFactory; + private readonly ResourceObjectDocumentationReader _resourceObjectDocumentationReader; public ResourceObjectSchemaGenerator(SchemaGenerator defaultSchemaGenerator, IResourceGraph resourceGraph, IJsonApiOptions options, ISchemaRepositoryAccessor schemaRepositoryAccessor, ResourceFieldValidationMetadataProvider resourceFieldValidationMetadataProvider) @@ -42,6 +43,8 @@ public ResourceObjectSchemaGenerator(SchemaGenerator defaultSchemaGenerator, IRe _resourceFieldObjectSchemaBuilderFactory = resourceTypeInfo => new ResourceFieldObjectSchemaBuilder(resourceTypeInfo, schemaRepositoryAccessor, defaultSchemaGenerator, _resourceTypeSchemaGenerator, options.SerializerOptions.PropertyNamingPolicy, resourceFieldValidationMetadataProvider); + + _resourceObjectDocumentationReader = new ResourceObjectDocumentationReader(); } public OpenApiSchema GenerateSchema(Type resourceObjectType) @@ -55,7 +58,7 @@ public OpenApiSchema GenerateSchema(Type resourceObjectType) RemoveResourceIdIfPostResourceObject(resourceTypeInfo, fullSchemaForResourceObject); - SetResourceType(fullSchemaForResourceObject, resourceTypeInfo.ResourceType.ClrType); + SetResourceType(fullSchemaForResourceObject, resourceTypeInfo.ResourceType); SetResourceAttributes(fullSchemaForResourceObject, fieldObjectBuilder); @@ -96,9 +99,11 @@ private void RemoveResourceIdIfPostResourceObject(ResourceTypeInfo resourceTypeI } } - private void SetResourceType(OpenApiSchema fullSchemaForResourceObject, Type resourceType) + private void SetResourceType(OpenApiSchema fullSchemaForResourceObject, ResourceType resourceType) { - fullSchemaForResourceObject.Properties[JsonApiPropertyName.Type] = _resourceTypeSchemaGenerator.Get(resourceType); + fullSchemaForResourceObject.Properties[JsonApiPropertyName.Type] = _resourceTypeSchemaGenerator.Get(resourceType.ClrType); + + fullSchemaForResourceObject.Description = _resourceObjectDocumentationReader.GetDocumentationForType(resourceType); } private void SetResourceAttributes(OpenApiSchema fullSchemaForResourceObject, ResourceFieldObjectSchemaBuilder builder) diff --git a/test/OpenApiClientTests/LegacyClient/swagger.g.json b/test/OpenApiClientTests/LegacyClient/swagger.g.json index 83a045edbd..246cd45865 100644 --- a/test/OpenApiClientTests/LegacyClient/swagger.g.json +++ b/test/OpenApiClientTests/LegacyClient/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "airplanes" ], + "summary": "Retrieves a collection of airplanes.", "operationId": "get-airplane-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found airplanes, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "airplanes" ], + "summary": "Retrieves a collection of airplanes without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/airplane-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "airplanes" ], + "summary": "Creates a new airplane.", "operationId": "post-airplane", "requestBody": { + "description": "The attributes and relationships of the airplane to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The airplane was successfully created, which resulted in additional changes. The newly created airplane is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The airplane was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves an individual airplane by its identifier.", "operationId": "get-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to retrieve.", "required": true, "schema": { "type": "string" @@ -91,7 +103,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found airplane.", "content": { "application/vnd.api+json": { "schema": { @@ -99,6 +111,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -106,11 +121,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves an individual airplane by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to retrieve.", "required": true, "schema": { "type": "string" @@ -119,14 +137,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/airplane-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -134,11 +148,13 @@ "tags": [ "airplanes" ], + "summary": "Updates an existing airplane.", "operationId": "patch-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to update.", "required": true, "schema": { "type": "string" @@ -146,6 +162,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the airplane to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -156,7 +173,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The airplane was successfully updated, which resulted in additional changes. The updated airplane is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -166,7 +183,19 @@ } }, "204": { - "description": "No Content" + "description": "The airplane was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The airplane or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -174,11 +203,13 @@ "tags": [ "airplanes" ], + "summary": "Deletes an existing airplane by its identifier.", "operationId": "delete-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to delete.", "required": true, "schema": { "type": "string" @@ -187,7 +218,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The airplane was successfully deleted." + }, + "404": { + "description": "The airplane does not exist." } } } @@ -197,11 +231,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flights of an individual airplane's flights relationship.", "operationId": "get-airplane-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -210,7 +246,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -218,6 +254,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -225,11 +264,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flights of an individual airplane's flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -238,14 +280,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } } @@ -255,11 +293,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flight identities of an individual airplane's flights relationship.", "operationId": "get-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -268,7 +308,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -276,6 +316,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -283,11 +326,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flight identities of an individual airplane's flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -296,14 +342,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -311,11 +353,13 @@ "tags": [ "airplanes" ], + "summary": "Adds existing flights to the flights relationship of an individual airplane.", "operationId": "post-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to add flights to.", "required": true, "schema": { "type": "string" @@ -323,6 +367,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -333,7 +378,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -341,11 +395,13 @@ "tags": [ "airplanes" ], + "summary": "Assigns existing flights to the flights relationship of an individual airplane.", "operationId": "patch-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -353,6 +409,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -363,7 +420,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -371,11 +437,13 @@ "tags": [ "airplanes" ], + "summary": "Removes existing flights from the flights relationship of an individual airplane.", "operationId": "delete-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to remove flights from.", "required": true, "schema": { "type": "string" @@ -383,6 +451,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -393,7 +462,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -403,10 +481,11 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves a collection of flight-attendants.", "operationId": "get-flight-attendant-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendants, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -421,17 +500,12 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves a collection of flight-attendants without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -439,8 +513,10 @@ "tags": [ "flight-attendants" ], + "summary": "Creates a new flight-attendant.", "operationId": "post-flight-attendant", "requestBody": { + "description": "The attributes and relationships of the flight-attendant to create.", "content": { "application/vnd.api+json": { "schema": { @@ -451,7 +527,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The flight-attendant was successfully created, which resulted in additional changes. The newly created flight-attendant is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -461,7 +537,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight-attendant was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -471,11 +559,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves an individual flight-attendant by its identifier.", "operationId": "get-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -484,7 +574,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant.", "content": { "application/vnd.api+json": { "schema": { @@ -492,6 +582,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -499,11 +592,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves an individual flight-attendant by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -512,14 +608,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -527,11 +619,13 @@ "tags": [ "flight-attendants" ], + "summary": "Updates an existing flight-attendant.", "operationId": "patch-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to update.", "required": true, "schema": { "type": "string" @@ -539,6 +633,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the flight-attendant to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -549,7 +644,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The flight-attendant was successfully updated, which resulted in additional changes. The updated flight-attendant is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -559,7 +654,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight-attendant was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -567,11 +674,13 @@ "tags": [ "flight-attendants" ], + "summary": "Deletes an existing flight-attendant by its identifier.", "operationId": "delete-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to delete.", "required": true, "schema": { "type": "string" @@ -580,7 +689,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The flight-attendant was successfully deleted." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -590,11 +702,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's purser-on-flights relationship.", "operationId": "get-flight-attendant-purser-on-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -603,7 +717,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -611,6 +725,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -618,11 +735,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's purser-on-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-purser-on-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -631,14 +751,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -648,11 +764,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's purser-on-flights relationship.", "operationId": "get-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -661,7 +779,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -669,6 +787,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -676,11 +797,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's purser-on-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -689,14 +813,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -704,11 +824,13 @@ "tags": [ "flight-attendants" ], + "summary": "Adds existing flights to the purser-on-flights relationship of an individual flight-attendant.", "operationId": "post-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to add flights to.", "required": true, "schema": { "type": "string" @@ -716,6 +838,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the purser-on-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -726,7 +849,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -734,11 +866,13 @@ "tags": [ "flight-attendants" ], + "summary": "Assigns existing flights to the purser-on-flights relationship of an individual flight-attendant.", "operationId": "patch-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose purser-on-flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -746,6 +880,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the purser-on-flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -756,7 +891,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The purser-on-flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -764,11 +908,13 @@ "tags": [ "flight-attendants" ], + "summary": "Removes existing flights from the purser-on-flights relationship of an individual flight-attendant.", "operationId": "delete-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to remove flights from.", "required": true, "schema": { "type": "string" @@ -776,6 +922,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the purser-on-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -786,7 +933,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -796,11 +952,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's scheduled-for-flights relationship.", "operationId": "get-flight-attendant-scheduled-for-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -809,7 +967,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -817,6 +975,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -824,11 +985,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's scheduled-for-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-scheduled-for-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -837,14 +1001,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -854,11 +1014,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's scheduled-for-flights relationship.", "operationId": "get-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -867,7 +1029,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -875,6 +1037,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -882,11 +1047,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's scheduled-for-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -895,14 +1063,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -910,11 +1074,13 @@ "tags": [ "flight-attendants" ], + "summary": "Adds existing flights to the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "post-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to add flights to.", "required": true, "schema": { "type": "string" @@ -922,6 +1088,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the scheduled-for-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -932,7 +1099,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -940,11 +1116,13 @@ "tags": [ "flight-attendants" ], + "summary": "Assigns existing flights to the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "patch-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose scheduled-for-flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -952,6 +1130,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the scheduled-for-flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -962,7 +1141,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The scheduled-for-flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -970,11 +1158,13 @@ "tags": [ "flight-attendants" ], + "summary": "Removes existing flights from the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "delete-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to remove flights from.", "required": true, "schema": { "type": "string" @@ -982,6 +1172,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the scheduled-for-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -992,7 +1183,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1002,10 +1202,11 @@ "tags": [ "flights" ], + "summary": "Retrieves a collection of flights.", "operationId": "get-flight-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1020,17 +1221,12 @@ "tags": [ "flights" ], + "summary": "Retrieves a collection of flights without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -1038,8 +1234,10 @@ "tags": [ "flights" ], + "summary": "Creates a new flight.", "operationId": "post-flight", "requestBody": { + "description": "The attributes and relationships of the flight to create.", "content": { "application/vnd.api+json": { "schema": { @@ -1050,7 +1248,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The flight was successfully created, which resulted in additional changes. The newly created flight is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -1060,7 +1258,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -1070,11 +1280,13 @@ "tags": [ "flights" ], + "summary": "Retrieves an individual flight by its identifier.", "operationId": "get-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to retrieve.", "required": true, "schema": { "type": "string" @@ -1083,7 +1295,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight.", "content": { "application/vnd.api+json": { "schema": { @@ -1091,6 +1303,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1098,11 +1313,14 @@ "tags": [ "flights" ], + "summary": "Retrieves an individual flight by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to retrieve.", "required": true, "schema": { "type": "string" @@ -1111,14 +1329,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1126,11 +1340,13 @@ "tags": [ "flights" ], + "summary": "Updates an existing flight.", "operationId": "patch-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to update.", "required": true, "schema": { "type": "string" @@ -1138,6 +1354,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the flight to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -1148,7 +1365,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The flight was successfully updated, which resulted in additional changes. The updated flight is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -1158,7 +1375,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -1166,11 +1395,13 @@ "tags": [ "flights" ], + "summary": "Deletes an existing flight by its identifier.", "operationId": "delete-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to delete.", "required": true, "schema": { "type": "string" @@ -1179,7 +1410,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The flight was successfully deleted." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1189,11 +1423,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's backup-purser relationship.", "operationId": "get-flight-backup-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1202,7 +1438,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1210,6 +1446,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1217,11 +1456,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's backup-purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-backup-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1230,14 +1472,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-flight-attendant-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1247,11 +1485,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's backup-purser relationship.", "operationId": "get-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1260,7 +1500,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1268,6 +1508,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1275,11 +1518,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's backup-purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1288,14 +1534,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-flight-attendant-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1303,11 +1545,13 @@ "tags": [ "flights" ], + "summary": "Clears or assigns an existing flight-attendant to the backup-purser relationship of an individual flight.", "operationId": "patch-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose backup-purser relationship to assign or clear.", "required": true, "schema": { "type": "string" @@ -1315,6 +1559,7 @@ } ], "requestBody": { + "description": "The identity of the flight-attendant to assign to the backup-purser relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1325,7 +1570,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The backup-purser relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1335,11 +1589,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendants of an individual flight's cabin-crew-members relationship.", "operationId": "get-flight-cabin-crew-members", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendants to retrieve.", "required": true, "schema": { "type": "string" @@ -1348,7 +1604,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendants, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1356,6 +1612,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1363,11 +1622,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendants of an individual flight's cabin-crew-members relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-cabin-crew-members", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendants to retrieve.", "required": true, "schema": { "type": "string" @@ -1376,14 +1638,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1393,11 +1651,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identities of an individual flight's cabin-crew-members relationship.", "operationId": "get-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1406,7 +1666,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1414,6 +1674,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1421,11 +1684,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identities of an individual flight's cabin-crew-members relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1434,14 +1700,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1449,11 +1711,13 @@ "tags": [ "flights" ], + "summary": "Adds existing flight-attendants to the cabin-crew-members relationship of an individual flight.", "operationId": "post-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to add flight-attendants to.", "required": true, "schema": { "type": "string" @@ -1461,6 +1725,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to add to the cabin-crew-members relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1471,7 +1736,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flight-attendants were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1479,11 +1753,13 @@ "tags": [ "flights" ], + "summary": "Assigns existing flight-attendants to the cabin-crew-members relationship of an individual flight.", "operationId": "patch-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose cabin-crew-members relationship to assign.", "required": true, "schema": { "type": "string" @@ -1491,6 +1767,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to assign to the cabin-crew-members relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1501,7 +1778,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The cabin-crew-members relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1509,11 +1795,13 @@ "tags": [ "flights" ], + "summary": "Removes existing flight-attendants from the cabin-crew-members relationship of an individual flight.", "operationId": "delete-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to remove flight-attendants from.", "required": true, "schema": { "type": "string" @@ -1521,6 +1809,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to remove from the cabin-crew-members relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1531,7 +1820,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flight-attendants were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1541,11 +1839,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passengers of an individual flight's passengers relationship.", "operationId": "get-flight-passengers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passengers to retrieve.", "required": true, "schema": { "type": "string" @@ -1554,7 +1854,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found passengers, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1562,6 +1862,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1569,11 +1872,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passengers of an individual flight's passengers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-passengers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passengers to retrieve.", "required": true, "schema": { "type": "string" @@ -1582,14 +1888,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/passenger-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1599,11 +1901,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passenger identities of an individual flight's passengers relationship.", "operationId": "get-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passenger identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1612,7 +1916,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found passenger identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1620,6 +1924,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1627,11 +1934,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passenger identities of an individual flight's passengers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passenger identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1640,14 +1950,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/passenger-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1655,11 +1961,13 @@ "tags": [ "flights" ], + "summary": "Adds existing passengers to the passengers relationship of an individual flight.", "operationId": "post-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to add passengers to.", "required": true, "schema": { "type": "string" @@ -1667,6 +1975,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to add to the passengers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1677,7 +1986,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1685,11 +2003,13 @@ "tags": [ "flights" ], + "summary": "Assigns existing passengers to the passengers relationship of an individual flight.", "operationId": "patch-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose passengers relationship to assign.", "required": true, "schema": { "type": "string" @@ -1697,6 +2017,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to assign to the passengers relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1707,7 +2028,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1715,11 +2045,13 @@ "tags": [ "flights" ], + "summary": "Removes existing passengers from the passengers relationship of an individual flight.", "operationId": "delete-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to remove passengers from.", "required": true, "schema": { "type": "string" @@ -1727,6 +2059,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to remove from the passengers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1737,7 +2070,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1747,11 +2089,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's purser relationship.", "operationId": "get-flight-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1760,7 +2104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1768,6 +2112,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1775,11 +2122,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1788,14 +2138,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1805,11 +2151,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's purser relationship.", "operationId": "get-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1818,7 +2166,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1826,6 +2174,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1833,11 +2184,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1846,14 +2200,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1861,11 +2211,13 @@ "tags": [ "flights" ], + "summary": "Assigns an existing flight-attendant to the purser relationship of an individual flight.", "operationId": "patch-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose purser relationship to assign.", "required": true, "schema": { "type": "string" @@ -1873,6 +2225,7 @@ } ], "requestBody": { + "description": "The identity of the flight-attendant to assign to the purser relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1883,7 +2236,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The purser relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1906,7 +2268,8 @@ "LufthansaGroup", "AirFranceKlm" ], - "type": "string" + "type": "string", + "description": "Lists the various airlines used in this API." }, "airplane-attributes-in-patch-request": { "type": "object", @@ -1996,6 +2359,7 @@ }, "manufactured-at": { "type": "string", + "description": "Gets the day on which this airplane was manufactured.", "format": "date-time" }, "is-in-maintenance": { diff --git a/test/OpenApiClientTests/NamingConventions/CamelCase/swagger.g.json b/test/OpenApiClientTests/NamingConventions/CamelCase/swagger.g.json index a477f7a7fb..36f4e576cb 100644 --- a/test/OpenApiClientTests/NamingConventions/CamelCase/swagger.g.json +++ b/test/OpenApiClientTests/NamingConventions/CamelCase/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves a collection of supermarkets.", "operationId": "getSupermarketCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found supermarkets, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves a collection of supermarkets without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/supermarketCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "supermarkets" ], + "summary": "Creates a new supermarket.", "operationId": "postSupermarket", "requestBody": { + "description": "The attributes and relationships of the supermarket to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The supermarket was successfully created, which resulted in additional changes. The newly created supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The supermarket was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves an individual supermarket by its identifier.", "operationId": "getSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found supermarket.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves an individual supermarket by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/supermarketPrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "supermarkets" ], + "summary": "Updates an existing supermarket.", "operationId": "patchSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the supermarket to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The supermarket was successfully updated, which resulted in additional changes. The updated supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The supermarket was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "supermarkets" ], + "summary": "Deletes an existing supermarket by its identifier.", "operationId": "deleteSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The supermarket was successfully deleted." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember of an individual supermarket's backupStoreManager relationship.", "operationId": "getSupermarketBackupStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMember, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember of an individual supermarket's backupStoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketBackupStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableStaffMemberSecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identity of an individual supermarket's backupStoreManager relationship.", "operationId": "getSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMember identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identity of an individual supermarket's backupStoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableStaffMemberIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "supermarkets" ], + "summary": "Clears or assigns an existing staffMember to the backupStoreManager relationship of an individual supermarket.", "operationId": "patchSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose backupStoreManager relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identity of the staffMember to assign to the backupStoreManager relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The backupStoreManager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -352,11 +406,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMembers of an individual supermarket's cashiers relationship.", "operationId": "getSupermarketCashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMembers to retrieve.", "required": true, "schema": { "type": "integer", @@ -366,7 +422,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMembers, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -374,6 +430,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -381,11 +440,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMembers of an individual supermarket's cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketCashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMembers to retrieve.", "required": true, "schema": { "type": "integer", @@ -395,14 +457,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staffMemberCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -412,11 +470,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identities of an individual supermarket's cashiers relationship.", "operationId": "getSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -426,7 +486,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMember identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -434,6 +494,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -441,11 +504,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identities of an individual supermarket's cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -455,14 +521,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staffMemberIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -470,11 +532,13 @@ "tags": [ "supermarkets" ], + "summary": "Adds existing staffMembers to the cashiers relationship of an individual supermarket.", "operationId": "postSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to add staffMembers to.", "required": true, "schema": { "type": "integer", @@ -483,6 +547,7 @@ } ], "requestBody": { + "description": "The identities of the staffMembers to add to the cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -493,7 +558,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The staffMembers were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -501,11 +575,13 @@ "tags": [ "supermarkets" ], + "summary": "Assigns existing staffMembers to the cashiers relationship of an individual supermarket.", "operationId": "patchSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose cashiers relationship to assign.", "required": true, "schema": { "type": "integer", @@ -514,6 +590,7 @@ } ], "requestBody": { + "description": "The identities of the staffMembers to assign to the cashiers relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -524,7 +601,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The cashiers relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -532,11 +618,13 @@ "tags": [ "supermarkets" ], + "summary": "Removes existing staffMembers from the cashiers relationship of an individual supermarket.", "operationId": "deleteSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to remove staffMembers from.", "required": true, "schema": { "type": "integer", @@ -545,6 +633,7 @@ } ], "requestBody": { + "description": "The identities of the staffMembers to remove from the cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -555,7 +644,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The staffMembers were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -565,11 +663,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember of an individual supermarket's storeManager relationship.", "operationId": "getSupermarketStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -579,7 +679,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMember, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -587,6 +687,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -594,11 +697,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember of an individual supermarket's storeManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -608,14 +714,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staffMemberSecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -625,11 +727,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identity of an individual supermarket's storeManager relationship.", "operationId": "getSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -639,7 +743,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staffMember identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -647,6 +751,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -654,11 +761,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staffMember identity of an individual supermarket's storeManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,14 +778,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staffMemberIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -683,11 +789,13 @@ "tags": [ "supermarkets" ], + "summary": "Assigns an existing staffMember to the storeManager relationship of an individual supermarket.", "operationId": "patchSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose storeManager relationship to assign.", "required": true, "schema": { "type": "integer", @@ -696,6 +804,7 @@ } ], "requestBody": { + "description": "The identity of the staffMember to assign to the storeManager relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -706,7 +815,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The storeManager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/NamingConventions/KebabCase/swagger.g.json b/test/OpenApiClientTests/NamingConventions/KebabCase/swagger.g.json index b818a08717..5f849605f2 100644 --- a/test/OpenApiClientTests/NamingConventions/KebabCase/swagger.g.json +++ b/test/OpenApiClientTests/NamingConventions/KebabCase/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves a collection of supermarkets.", "operationId": "get-supermarket-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found supermarkets, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves a collection of supermarkets without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/supermarket-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "supermarkets" ], + "summary": "Creates a new supermarket.", "operationId": "post-supermarket", "requestBody": { + "description": "The attributes and relationships of the supermarket to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The supermarket was successfully created, which resulted in additional changes. The newly created supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The supermarket was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves an individual supermarket by its identifier.", "operationId": "get-supermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found supermarket.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves an individual supermarket by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/supermarket-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "supermarkets" ], + "summary": "Updates an existing supermarket.", "operationId": "patch-supermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the supermarket to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The supermarket was successfully updated, which resulted in additional changes. The updated supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The supermarket was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "supermarkets" ], + "summary": "Deletes an existing supermarket by its identifier.", "operationId": "delete-supermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The supermarket was successfully deleted." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member of an individual supermarket's backup-store-manager relationship.", "operationId": "get-supermarket-backup-store-manager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-member, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member of an individual supermarket's backup-store-manager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-backup-store-manager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-staff-member-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identity of an individual supermarket's backup-store-manager relationship.", "operationId": "get-supermarket-backup-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-member identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identity of an individual supermarket's backup-store-manager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-backup-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-staff-member-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "supermarkets" ], + "summary": "Clears or assigns an existing staff-member to the backup-store-manager relationship of an individual supermarket.", "operationId": "patch-supermarket-backup-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose backup-store-manager relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identity of the staff-member to assign to the backup-store-manager relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The backup-store-manager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -352,11 +406,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-members of an individual supermarket's cashiers relationship.", "operationId": "get-supermarket-cashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-members to retrieve.", "required": true, "schema": { "type": "integer", @@ -366,7 +422,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-members, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -374,6 +430,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -381,11 +440,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-members of an individual supermarket's cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-cashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-members to retrieve.", "required": true, "schema": { "type": "integer", @@ -395,14 +457,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staff-member-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -412,11 +470,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identities of an individual supermarket's cashiers relationship.", "operationId": "get-supermarket-cashiers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -426,7 +486,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-member identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -434,6 +494,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -441,11 +504,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identities of an individual supermarket's cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-cashiers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -455,14 +521,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staff-member-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -470,11 +532,13 @@ "tags": [ "supermarkets" ], + "summary": "Adds existing staff-members to the cashiers relationship of an individual supermarket.", "operationId": "post-supermarket-cashiers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to add staff-members to.", "required": true, "schema": { "type": "integer", @@ -483,6 +547,7 @@ } ], "requestBody": { + "description": "The identities of the staff-members to add to the cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -493,7 +558,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The staff-members were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -501,11 +575,13 @@ "tags": [ "supermarkets" ], + "summary": "Assigns existing staff-members to the cashiers relationship of an individual supermarket.", "operationId": "patch-supermarket-cashiers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose cashiers relationship to assign.", "required": true, "schema": { "type": "integer", @@ -514,6 +590,7 @@ } ], "requestBody": { + "description": "The identities of the staff-members to assign to the cashiers relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -524,7 +601,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The cashiers relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -532,11 +618,13 @@ "tags": [ "supermarkets" ], + "summary": "Removes existing staff-members from the cashiers relationship of an individual supermarket.", "operationId": "delete-supermarket-cashiers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket to remove staff-members from.", "required": true, "schema": { "type": "integer", @@ -545,6 +633,7 @@ } ], "requestBody": { + "description": "The identities of the staff-members to remove from the cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -555,7 +644,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The staff-members were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -565,11 +663,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member of an individual supermarket's store-manager relationship.", "operationId": "get-supermarket-store-manager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member to retrieve.", "required": true, "schema": { "type": "integer", @@ -579,7 +679,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-member, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -587,6 +687,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -594,11 +697,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member of an individual supermarket's store-manager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-store-manager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member to retrieve.", "required": true, "schema": { "type": "integer", @@ -608,14 +714,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staff-member-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } } @@ -625,11 +727,13 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identity of an individual supermarket's store-manager relationship.", "operationId": "get-supermarket-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -639,7 +743,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found staff-member identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -647,6 +751,9 @@ } } } + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -654,11 +761,14 @@ "tags": [ "supermarkets" ], + "summary": "Retrieves the related staff-member identity of an individual supermarket's store-manager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-supermarket-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose related staff-member identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,14 +778,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/staff-member-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The supermarket does not exist." } } }, @@ -683,11 +789,13 @@ "tags": [ "supermarkets" ], + "summary": "Assigns an existing staff-member to the store-manager relationship of an individual supermarket.", "operationId": "patch-supermarket-store-manager-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the supermarket whose store-manager relationship to assign.", "required": true, "schema": { "type": "integer", @@ -696,6 +804,7 @@ } ], "requestBody": { + "description": "The identity of the staff-member to assign to the store-manager relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -706,7 +815,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The store-manager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/NamingConventions/PascalCase/swagger.g.json b/test/OpenApiClientTests/NamingConventions/PascalCase/swagger.g.json index 80c5fedf0c..20ecb900cd 100644 --- a/test/OpenApiClientTests/NamingConventions/PascalCase/swagger.g.json +++ b/test/OpenApiClientTests/NamingConventions/PascalCase/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves a collection of Supermarkets.", "operationId": "GetSupermarketCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found Supermarkets, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves a collection of Supermarkets without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/SupermarketCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "Supermarkets" ], + "summary": "Creates a new Supermarket.", "operationId": "PostSupermarket", "requestBody": { + "description": "The attributes and relationships of the Supermarket to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The Supermarket was successfully created, which resulted in additional changes. The newly created Supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The Supermarket was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves an individual Supermarket by its identifier.", "operationId": "GetSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found Supermarket.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves an individual Supermarket by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/SupermarketPrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "Supermarkets" ], + "summary": "Updates an existing Supermarket.", "operationId": "PatchSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the Supermarket to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The Supermarket was successfully updated, which resulted in additional changes. The updated Supermarket is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The Supermarket was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "Supermarkets" ], + "summary": "Deletes an existing Supermarket by its identifier.", "operationId": "DeleteSupermarket", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The Supermarket was successfully deleted." + }, + "404": { + "description": "The Supermarket does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember of an individual Supermarket's BackupStoreManager relationship.", "operationId": "GetSupermarketBackupStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMember, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember of an individual Supermarket's BackupStoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketBackupStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/NullableStaffMemberSecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identity of an individual Supermarket's BackupStoreManager relationship.", "operationId": "GetSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMember identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identity of an individual Supermarket's BackupStoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/NullableStaffMemberIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "Supermarkets" ], + "summary": "Clears or assigns an existing StaffMember to the BackupStoreManager relationship of an individual Supermarket.", "operationId": "PatchSupermarketBackupStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose BackupStoreManager relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identity of the StaffMember to assign to the BackupStoreManager relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The BackupStoreManager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -352,11 +406,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMembers of an individual Supermarket's Cashiers relationship.", "operationId": "GetSupermarketCashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMembers to retrieve.", "required": true, "schema": { "type": "integer", @@ -366,7 +422,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMembers, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -374,6 +430,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -381,11 +440,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMembers of an individual Supermarket's Cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketCashiers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMembers to retrieve.", "required": true, "schema": { "type": "integer", @@ -395,14 +457,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/StaffMemberCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } } @@ -412,11 +470,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identities of an individual Supermarket's Cashiers relationship.", "operationId": "GetSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -426,7 +486,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMember identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -434,6 +494,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -441,11 +504,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identities of an individual Supermarket's Cashiers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -455,14 +521,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/StaffMemberIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -470,11 +532,13 @@ "tags": [ "Supermarkets" ], + "summary": "Adds existing StaffMembers to the Cashiers relationship of an individual Supermarket.", "operationId": "PostSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to add StaffMembers to.", "required": true, "schema": { "type": "integer", @@ -483,6 +547,7 @@ } ], "requestBody": { + "description": "The identities of the StaffMembers to add to the Cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -493,7 +558,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The StaffMembers were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -501,11 +575,13 @@ "tags": [ "Supermarkets" ], + "summary": "Assigns existing StaffMembers to the Cashiers relationship of an individual Supermarket.", "operationId": "PatchSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose Cashiers relationship to assign.", "required": true, "schema": { "type": "integer", @@ -514,6 +590,7 @@ } ], "requestBody": { + "description": "The identities of the StaffMembers to assign to the Cashiers relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -524,7 +601,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The Cashiers relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -532,11 +618,13 @@ "tags": [ "Supermarkets" ], + "summary": "Removes existing StaffMembers from the Cashiers relationship of an individual Supermarket.", "operationId": "DeleteSupermarketCashiersRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket to remove StaffMembers from.", "required": true, "schema": { "type": "integer", @@ -545,6 +633,7 @@ } ], "requestBody": { + "description": "The identities of the StaffMembers to remove from the Cashiers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -555,7 +644,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The StaffMembers were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -565,11 +663,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember of an individual Supermarket's StoreManager relationship.", "operationId": "GetSupermarketStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -579,7 +679,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMember, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -587,6 +687,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -594,11 +697,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember of an individual Supermarket's StoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketStoreManager", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember to retrieve.", "required": true, "schema": { "type": "integer", @@ -608,14 +714,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/StaffMemberSecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } } @@ -625,11 +727,13 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identity of an individual Supermarket's StoreManager relationship.", "operationId": "GetSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -639,7 +743,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found StaffMember identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -647,6 +751,9 @@ } } } + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -654,11 +761,14 @@ "tags": [ "Supermarkets" ], + "summary": "Retrieves the related StaffMember identity of an individual Supermarket's StoreManager relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "HeadSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose related StaffMember identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,14 +778,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/StaffMemberIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The Supermarket does not exist." } } }, @@ -683,11 +789,13 @@ "tags": [ "Supermarkets" ], + "summary": "Assigns an existing StaffMember to the StoreManager relationship of an individual Supermarket.", "operationId": "PatchSupermarketStoreManagerRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the Supermarket whose StoreManager relationship to assign.", "required": true, "schema": { "type": "integer", @@ -696,6 +804,7 @@ } ], "requestBody": { + "description": "The identity of the StaffMember to assign to the StoreManager relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -706,7 +815,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The StoreManager relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The Supermarket does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/swagger.g.json b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/swagger.g.json index 9f87d2acb5..6a62f505a2 100644 --- a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/swagger.g.json +++ b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources.", "operationId": "getResourceCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resources, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourceCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "resources" ], + "summary": "Creates a new resource.", "operationId": "postResource", "requestBody": { + "description": "The attributes and relationships of the resource to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The resource was successfully created, which resulted in additional changes. The newly created resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier.", "operationId": "getResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resource.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourcePrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "resources" ], + "summary": "Updates an existing resource.", "operationId": "patchResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the resource to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The resource was successfully updated, which resulted in additional changes. The updated resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "resources" ], + "summary": "Deletes an existing resource by its identifier.", "operationId": "deleteResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The resource was successfully deleted." + }, + "404": { + "description": "The resource does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the requiredToMany relationship of an individual resource.", "operationId": "postResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -350,11 +404,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the requiredToMany relationship of an individual resource.", "operationId": "patchResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -363,6 +419,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the requiredToMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -373,7 +430,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -381,11 +447,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the requiredToMany relationship of an individual resource.", "operationId": "deleteResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -394,6 +462,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -404,7 +473,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -414,11 +492,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredToOne relationship.", "operationId": "getResourceRequiredToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -428,7 +508,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -436,6 +516,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -443,11 +526,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -457,14 +543,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -474,11 +556,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredToOne relationship.", "operationId": "getResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -488,7 +572,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -496,6 +580,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -503,11 +590,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -517,14 +607,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -532,11 +618,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the requiredToOne relationship of an individual resource.", "operationId": "patchResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -545,6 +633,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredToOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -555,7 +644,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -565,11 +663,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship.", "operationId": "getResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -579,7 +679,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -587,6 +687,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -594,11 +697,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -608,14 +714,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -625,11 +727,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship.", "operationId": "getResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -639,7 +743,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -647,6 +751,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -654,11 +761,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,14 +778,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -683,11 +789,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the toMany relationship of an individual resource.", "operationId": "postResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -696,6 +804,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -706,7 +815,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -714,11 +832,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the toMany relationship of an individual resource.", "operationId": "patchResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -727,6 +847,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the toMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -737,7 +858,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -745,11 +875,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the toMany relationship of an individual resource.", "operationId": "deleteResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -758,6 +890,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -768,7 +901,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -778,11 +920,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's toOne relationship.", "operationId": "getResourceToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -792,7 +936,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -800,6 +944,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -807,11 +954,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's toOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -821,14 +971,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -838,11 +984,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's toOne relationship.", "operationId": "getResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -852,7 +1000,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -860,6 +1008,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -867,11 +1018,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's toOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -881,14 +1035,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -896,11 +1046,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the toOne relationship of an individual resource.", "operationId": "patchResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -909,6 +1061,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the toOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -919,7 +1072,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/swagger.g.json b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/swagger.g.json index 2f81c0ad70..8dd6c83f5c 100644 --- a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/swagger.g.json +++ b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources.", "operationId": "getResourceCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resources, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourceCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "resources" ], + "summary": "Creates a new resource.", "operationId": "postResource", "requestBody": { + "description": "The attributes and relationships of the resource to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The resource was successfully created, which resulted in additional changes. The newly created resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier.", "operationId": "getResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resource.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourcePrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "resources" ], + "summary": "Updates an existing resource.", "operationId": "patchResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the resource to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The resource was successfully updated, which resulted in additional changes. The updated resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "resources" ], + "summary": "Deletes an existing resource by its identifier.", "operationId": "deleteResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The resource was successfully deleted." + }, + "404": { + "description": "The resource does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the requiredToMany relationship of an individual resource.", "operationId": "postResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -350,11 +404,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the requiredToMany relationship of an individual resource.", "operationId": "patchResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -363,6 +419,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the requiredToMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -373,7 +430,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -381,11 +447,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the requiredToMany relationship of an individual resource.", "operationId": "deleteResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -394,6 +462,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -404,7 +473,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -414,11 +492,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredToOne relationship.", "operationId": "getResourceRequiredToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -428,7 +508,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -436,6 +516,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -443,11 +526,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -457,14 +543,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -474,11 +556,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredToOne relationship.", "operationId": "getResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -488,7 +572,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -496,6 +580,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -503,11 +590,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -517,14 +607,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -532,11 +618,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the requiredToOne relationship of an individual resource.", "operationId": "patchResourceRequiredToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -545,6 +633,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -555,7 +644,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -565,11 +663,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship.", "operationId": "getResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -579,7 +679,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -587,6 +687,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -594,11 +697,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -608,14 +714,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -625,11 +727,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship.", "operationId": "getResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -639,7 +743,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -647,6 +751,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -654,11 +761,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,14 +778,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -683,11 +789,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the toMany relationship of an individual resource.", "operationId": "postResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -696,6 +804,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -706,7 +815,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -714,11 +832,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the toMany relationship of an individual resource.", "operationId": "patchResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -727,6 +847,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the toMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -737,7 +858,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -745,11 +875,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the toMany relationship of an individual resource.", "operationId": "deleteResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -758,6 +890,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -768,7 +901,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -778,11 +920,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's toOne relationship.", "operationId": "getResourceToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -792,7 +936,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -800,6 +944,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -807,11 +954,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's toOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -821,14 +971,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -838,11 +984,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's toOne relationship.", "operationId": "getResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -852,7 +1000,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -860,6 +1008,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -867,11 +1018,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's toOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -881,14 +1035,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -896,11 +1046,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the toOne relationship of an individual resource.", "operationId": "patchResourceToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -909,6 +1061,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the toOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -919,7 +1072,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/swagger.g.json b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/swagger.g.json index 10d4fcd80e..ecd6333fbd 100644 --- a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/swagger.g.json +++ b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources.", "operationId": "getResourceCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resources, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourceCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "resources" ], + "summary": "Creates a new resource.", "operationId": "postResource", "requestBody": { + "description": "The attributes and relationships of the resource to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The resource was successfully created, which resulted in additional changes. The newly created resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier.", "operationId": "getResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resource.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourcePrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "resources" ], + "summary": "Updates an existing resource.", "operationId": "patchResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the resource to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The resource was successfully updated, which resulted in additional changes. The updated resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "resources" ], + "summary": "Deletes an existing resource by its identifier.", "operationId": "deleteResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The resource was successfully deleted." + }, + "404": { + "description": "The resource does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nonNullableToOne relationship.", "operationId": "getResourceNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nonNullableToOne relationship.", "operationId": "getResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the nonNullableToOne relationship of an individual resource.", "operationId": "patchResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose nonNullableToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the nonNullableToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The nonNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -352,11 +406,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nullableToOne relationship.", "operationId": "getResourceNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -366,7 +422,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -374,6 +430,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -381,11 +440,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -395,14 +457,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -412,11 +470,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nullableToOne relationship.", "operationId": "getResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -426,7 +486,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -434,6 +494,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -441,11 +504,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -455,14 +521,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -470,11 +532,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the nullableToOne relationship of an individual resource.", "operationId": "patchResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose nullableToOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -483,6 +547,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the nullableToOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -493,7 +558,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The nullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -503,11 +577,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNonNullableToOne relationship.", "operationId": "getResourceRequiredNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -517,7 +593,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -525,6 +601,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -532,11 +611,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -546,14 +628,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -563,11 +641,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNonNullableToOne relationship.", "operationId": "getResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -577,7 +657,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -585,6 +665,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -592,11 +675,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -606,14 +692,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -621,11 +703,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the requiredNonNullableToOne relationship of an individual resource.", "operationId": "patchResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredNonNullableToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -634,6 +718,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredNonNullableToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -644,7 +729,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredNonNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -654,11 +748,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNullableToOne relationship.", "operationId": "getResourceRequiredNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,7 +764,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -676,6 +772,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -683,11 +782,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -697,14 +799,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -714,11 +812,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNullableToOne relationship.", "operationId": "getResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -728,7 +828,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -736,6 +836,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -743,11 +846,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -757,14 +863,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -772,11 +874,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the requiredNullableToOne relationship of an individual resource.", "operationId": "patchResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredNullableToOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -785,6 +889,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredNullableToOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -795,7 +900,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -805,11 +919,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -819,7 +935,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -827,6 +943,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -834,11 +953,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -848,14 +970,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -865,11 +983,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -879,7 +999,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -887,6 +1007,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -894,11 +1017,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -908,14 +1034,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -923,11 +1045,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the requiredToMany relationship of an individual resource.", "operationId": "postResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -936,6 +1060,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -946,7 +1071,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -954,11 +1088,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the requiredToMany relationship of an individual resource.", "operationId": "patchResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -967,6 +1103,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the requiredToMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -977,7 +1114,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -985,11 +1131,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the requiredToMany relationship of an individual resource.", "operationId": "deleteResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -998,6 +1146,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1008,7 +1157,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1018,11 +1176,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship.", "operationId": "getResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -1032,7 +1192,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1040,6 +1200,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1047,11 +1210,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -1061,14 +1227,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -1078,11 +1240,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship.", "operationId": "getResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -1092,7 +1256,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1100,6 +1264,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1107,11 +1274,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -1121,14 +1291,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1136,11 +1302,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the toMany relationship of an individual resource.", "operationId": "postResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -1149,6 +1317,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1159,7 +1328,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1167,11 +1345,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the toMany relationship of an individual resource.", "operationId": "patchResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -1180,6 +1360,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the toMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1190,7 +1371,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1198,11 +1388,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the toMany relationship of an individual resource.", "operationId": "deleteResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -1211,6 +1403,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1221,7 +1414,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/swagger.g.json b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/swagger.g.json index 1f610c0c5a..f751eac3b2 100644 --- a/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/swagger.g.json +++ b/test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/swagger.g.json @@ -10,10 +10,11 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources.", "operationId": "getResourceCollection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resources, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "resources" ], + "summary": "Retrieves a collection of resources without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceCollection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourceCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "resources" ], + "summary": "Creates a new resource.", "operationId": "postResource", "requestBody": { + "description": "The attributes and relationships of the resource to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The resource was successfully created, which resulted in additional changes. The newly created resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier.", "operationId": "getResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -92,7 +104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found resource.", "content": { "application/vnd.api+json": { "schema": { @@ -100,6 +112,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -107,11 +122,14 @@ "tags": [ "resources" ], + "summary": "Retrieves an individual resource by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to retrieve.", "required": true, "schema": { "type": "integer", @@ -121,14 +139,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/resourcePrimaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -136,11 +150,13 @@ "tags": [ "resources" ], + "summary": "Updates an existing resource.", "operationId": "patchResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to update.", "required": true, "schema": { "type": "integer", @@ -149,6 +165,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the resource to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -159,7 +176,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The resource was successfully updated, which resulted in additional changes. The updated resource is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -169,7 +186,19 @@ } }, "204": { - "description": "No Content" + "description": "The resource was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -177,11 +206,13 @@ "tags": [ "resources" ], + "summary": "Deletes an existing resource by its identifier.", "operationId": "deleteResource", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to delete.", "required": true, "schema": { "type": "integer", @@ -191,7 +222,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The resource was successfully deleted." + }, + "404": { + "description": "The resource does not exist." } } } @@ -201,11 +235,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nonNullableToOne relationship.", "operationId": "getResourceNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -215,7 +251,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -223,6 +259,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -230,11 +269,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -244,14 +286,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -261,11 +299,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nonNullableToOne relationship.", "operationId": "getResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -275,7 +315,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -283,6 +323,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -290,11 +333,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -304,14 +350,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -319,11 +361,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the nonNullableToOne relationship of an individual resource.", "operationId": "patchResourceNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose nonNullableToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -332,6 +376,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the nonNullableToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -342,7 +387,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The nonNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -352,11 +406,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nullableToOne relationship.", "operationId": "getResourceNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -366,7 +422,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -374,6 +430,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -381,11 +440,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's nullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -395,14 +457,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -412,11 +470,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nullableToOne relationship.", "operationId": "getResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -426,7 +486,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -434,6 +494,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -441,11 +504,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's nullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -455,14 +521,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullableEmptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -470,11 +532,13 @@ "tags": [ "resources" ], + "summary": "Clears or assigns an existing empty to the nullableToOne relationship of an individual resource.", "operationId": "patchResourceNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose nullableToOne relationship to assign or clear.", "required": true, "schema": { "type": "integer", @@ -483,6 +547,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the nullableToOne relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -493,7 +558,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The nullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -503,11 +577,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNonNullableToOne relationship.", "operationId": "getResourceRequiredNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -517,7 +593,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -525,6 +601,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -532,11 +611,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNonNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -546,14 +628,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -563,11 +641,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNonNullableToOne relationship.", "operationId": "getResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -577,7 +657,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -585,6 +665,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -592,11 +675,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNonNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -606,14 +692,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -621,11 +703,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the requiredNonNullableToOne relationship of an individual resource.", "operationId": "patchResourceRequiredNonNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredNonNullableToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -634,6 +718,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredNonNullableToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -644,7 +729,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredNonNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -654,11 +748,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNullableToOne relationship.", "operationId": "getResourceRequiredNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -668,7 +764,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -676,6 +772,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -683,11 +782,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty of an individual resource's requiredNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNullableToOne", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty to retrieve.", "required": true, "schema": { "type": "integer", @@ -697,14 +799,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptySecondaryResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -714,11 +812,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNullableToOne relationship.", "operationId": "getResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -728,7 +828,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -736,6 +836,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -743,11 +846,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identity of an individual resource's requiredNullableToOne relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identity to retrieve.", "required": true, "schema": { "type": "integer", @@ -757,14 +863,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -772,11 +874,13 @@ "tags": [ "resources" ], + "summary": "Assigns an existing empty to the requiredNullableToOne relationship of an individual resource.", "operationId": "patchResourceRequiredNullableToOneRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredNullableToOne relationship to assign.", "required": true, "schema": { "type": "integer", @@ -785,6 +889,7 @@ } ], "requestBody": { + "description": "The identity of the empty to assign to the requiredNullableToOne relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -795,7 +900,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredNullableToOne relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -805,11 +919,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -819,7 +935,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -827,6 +943,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -834,11 +953,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -848,14 +970,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -865,11 +983,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship.", "operationId": "getResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -879,7 +999,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -887,6 +1007,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -894,11 +1017,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's requiredToMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -908,14 +1034,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -923,11 +1045,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the requiredToMany relationship of an individual resource.", "operationId": "postResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -936,6 +1060,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -946,7 +1071,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -954,11 +1088,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the requiredToMany relationship of an individual resource.", "operationId": "patchResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose requiredToMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -967,6 +1103,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the requiredToMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -977,7 +1114,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The requiredToMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -985,11 +1131,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the requiredToMany relationship of an individual resource.", "operationId": "deleteResourceRequiredToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -998,6 +1146,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the requiredToMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1008,7 +1157,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1018,11 +1176,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship.", "operationId": "getResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -1032,7 +1192,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empties, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1040,6 +1200,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1047,11 +1210,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empties of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToMany", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empties to retrieve.", "required": true, "schema": { "type": "integer", @@ -1061,14 +1227,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } } @@ -1078,11 +1240,13 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship.", "operationId": "getResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -1092,7 +1256,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found empty identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1100,6 +1264,9 @@ } } } + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1107,11 +1274,14 @@ "tags": [ "resources" ], + "summary": "Retrieves the related empty identities of an individual resource's toMany relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "headResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose related empty identities to retrieve.", "required": true, "schema": { "type": "integer", @@ -1121,14 +1291,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/emptyIdentifierCollectionResponseDocument" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The resource does not exist." } } }, @@ -1136,11 +1302,13 @@ "tags": [ "resources" ], + "summary": "Adds existing empties to the toMany relationship of an individual resource.", "operationId": "postResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to add empties to.", "required": true, "schema": { "type": "integer", @@ -1149,6 +1317,7 @@ } ], "requestBody": { + "description": "The identities of the empties to add to the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1159,7 +1328,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1167,11 +1345,13 @@ "tags": [ "resources" ], + "summary": "Assigns existing empties to the toMany relationship of an individual resource.", "operationId": "patchResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource whose toMany relationship to assign.", "required": true, "schema": { "type": "integer", @@ -1180,6 +1360,7 @@ } ], "requestBody": { + "description": "The identities of the empties to assign to the toMany relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1190,7 +1371,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The toMany relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1198,11 +1388,13 @@ "tags": [ "resources" ], + "summary": "Removes existing empties from the toMany relationship of an individual resource.", "operationId": "deleteResourceToManyRelationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the resource to remove empties from.", "required": true, "schema": { "type": "integer", @@ -1211,6 +1403,7 @@ } ], "requestBody": { + "description": "The identities of the empties to remove from the toMany relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1221,7 +1414,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The empties were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } diff --git a/test/OpenApiTests/DocComments/DocCommentsDbContext.cs b/test/OpenApiTests/DocComments/DocCommentsDbContext.cs new file mode 100644 index 0000000000..e296e5abd4 --- /dev/null +++ b/test/OpenApiTests/DocComments/DocCommentsDbContext.cs @@ -0,0 +1,30 @@ +using JetBrains.Annotations; +using Microsoft.EntityFrameworkCore; +using TestBuildingBlocks; + +// @formatter:wrap_chained_method_calls chop_always + +namespace OpenApiTests.DocComments; + +[UsedImplicitly(ImplicitUseTargetFlags.Members)] +public sealed class DocCommentsDbContext : TestableDbContext +{ + public DbSet Skyscrapers => Set(); + public DbSet Elevators => Set(); + public DbSet Spaces => Set(); + + public DocCommentsDbContext(DbContextOptions options) + : base(options) + { + } + + protected override void OnModelCreating(ModelBuilder builder) + { + builder.Entity() + .HasOne(skyscraper => skyscraper.Elevator) + .WithOne(elevator => elevator.ExistsIn) + .HasForeignKey("ElevatorId"); + + base.OnModelCreating(builder); + } +} diff --git a/test/OpenApiTests/DocComments/DocCommentsStartup.cs b/test/OpenApiTests/DocComments/DocCommentsStartup.cs new file mode 100644 index 0000000000..6049d701b1 --- /dev/null +++ b/test/OpenApiTests/DocComments/DocCommentsStartup.cs @@ -0,0 +1,41 @@ +using JetBrains.Annotations; +using JsonApiDotNetCore.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.OpenApi.Models; +using Swashbuckle.AspNetCore.SwaggerGen; +using TestBuildingBlocks; + +namespace OpenApiTests.DocComments; + +[UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)] +public sealed class DocCommentsStartup : OpenApiStartup + where TDbContext : TestableDbContext +{ + protected override void SetJsonApiOptions(JsonApiOptions options) + { + options.ClientIdGeneration = ClientIdGenerationMode.Allowed; + base.SetJsonApiOptions(options); + } + + protected override void SetupSwaggerGenAction(SwaggerGenOptions options) + { + options.SwaggerDoc("v1", new OpenApiInfo + { + Version = "v1", + Title = "Skyscrapers of the world", + Description = "A JSON:API service for managing skyscrapers.", + Contact = new OpenApiContact + { + Name = "Report issues", + Url = new Uri("https://github.com/json-api-dotnet/JsonApiDotNetCore/issues") + }, + License = new OpenApiLicense + { + Name = "MIT License", + Url = new Uri("https://licenses.nuget.org/MIT") + } + }); + + base.SetupSwaggerGenAction(options); + } +} diff --git a/test/OpenApiTests/DocComments/DocCommentsTests.cs b/test/OpenApiTests/DocComments/DocCommentsTests.cs new file mode 100644 index 0000000000..cf14cf66fa --- /dev/null +++ b/test/OpenApiTests/DocComments/DocCommentsTests.cs @@ -0,0 +1,499 @@ +using System.Text.Json; +using TestBuildingBlocks; +using Xunit; + +// @formatter:max_line_length 250 + +namespace OpenApiTests.DocComments; + +public sealed class DocCommentsTests : IClassFixture, DocCommentsDbContext>> +{ + private readonly OpenApiTestContext, DocCommentsDbContext> _testContext; + + public DocCommentsTests(OpenApiTestContext, DocCommentsDbContext> testContext) + { + _testContext = testContext; + + testContext.UseController(); + testContext.UseController(); + testContext.UseController(); + } + + [Fact] + public async Task API_is_documented() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("info").With(infoElement => + { + infoElement.Should().HaveProperty("title", "Skyscrapers of the world"); + infoElement.Should().HaveProperty("description", "A JSON:API service for managing skyscrapers."); + infoElement.Should().HaveProperty("version", "v1"); + + infoElement.Should().ContainPath("contact").With(contactElement => + { + contactElement.Should().HaveProperty("name", "Report issues"); + contactElement.Should().HaveProperty("url", "https://github.com/json-api-dotnet/JsonApiDotNetCore/issues"); + }); + + infoElement.Should().ContainPath("license").With(contactElement => + { + contactElement.Should().HaveProperty("name", "MIT License"); + contactElement.Should().HaveProperty("url", "https://licenses.nuget.org/MIT"); + }); + }); + } + + [Fact] + public async Task Endpoints_are_documented() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("paths./skyscrapers").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves a collection of skyscrapers."); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(1); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found skyscrapers, or an empty array if none were found."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves a collection of skyscrapers without returning them."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(1); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + }); + }); + + skyscrapersElement.Should().ContainPath("post").With(postElement => + { + postElement.Should().HaveProperty("summary", "Creates a new skyscraper."); + + postElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(5); + responseElement.Should().HaveProperty("201.description", "The skyscraper was successfully created, which resulted in additional changes. The newly created skyscraper is returned."); + responseElement.Should().HaveProperty("204.description", "The skyscraper was successfully created, which did not result in additional changes."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible."); + responseElement.Should().HaveProperty("422.description", "Validation of the request body failed."); + }); + }); + }); + + document.Should().ContainPath("paths./skyscrapers/{id}").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves an individual skyscraper by its identifier."); + + getElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to retrieve."); + }); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found skyscraper."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves an individual skyscraper by its identifier without returning it."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to retrieve."); + }); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("patch").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Updates an existing skyscraper."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to update."); + }); + + patchElement.Should().HaveProperty("requestBody.description", "The attributes and relationships of the skyscraper to update. Omitted fields are left unchanged."); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(6); + responseElement.Should().HaveProperty("200.description", "The skyscraper was successfully updated, which resulted in additional changes. The updated skyscraper is returned."); + responseElement.Should().HaveProperty("204.description", "The skyscraper was successfully updated, which did not result in additional changes."); + responseElement.Should().HaveProperty("404.description", "The skyscraper or a related resource does not exist."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type or identifier in the request body is incompatible."); + responseElement.Should().HaveProperty("422.description", "Validation of the request body failed."); + }); + }); + + skyscrapersElement.Should().ContainPath("delete").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Deletes an existing skyscraper by its identifier."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to delete."); + }); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("204.description", "The skyscraper was successfully deleted."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + }); + + document.Should().ContainPath("paths./skyscrapers/{id}/elevator").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves the related elevator of an individual skyscraper's elevator relationship."); + + getElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related elevator to retrieve."); + }); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found elevator, or `null` if it was not found."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves the related elevator of an individual skyscraper's elevator relationship without returning it."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related elevator to retrieve."); + }); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + }); + + document.Should().ContainPath("paths./skyscrapers/{id}/relationships/elevator").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves the related elevator identity of an individual skyscraper's elevator relationship."); + + getElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related elevator identity to retrieve."); + }); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found elevator identity, or `null` if it was not found."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves the related elevator identity of an individual skyscraper's elevator relationship without returning it."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related elevator identity to retrieve."); + }); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("patch").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Clears or assigns an existing elevator to the elevator relationship of an individual skyscraper."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose elevator relationship to assign or clear."); + }); + + patchElement.Should().HaveProperty("requestBody.description", "The identity of the elevator to assign to the elevator relationship, or `null` to clear the relationship."); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(4); + responseElement.Should().HaveProperty("204.description", "The elevator relationship was successfully updated, which did not result in additional changes."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible."); + }); + }); + }); + + document.Should().ContainPath("paths./skyscrapers/{id}/spaces").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves the related spaces of an individual skyscraper's spaces relationship."); + + getElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related spaces to retrieve."); + }); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found spaces, or an empty array if none were found."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves the related spaces of an individual skyscraper's spaces relationship without returning them."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related spaces to retrieve."); + }); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + }); + + document.Should().ContainPath("paths./skyscrapers/{id}/relationships/spaces").With(skyscrapersElement => + { + skyscrapersElement.Should().ContainPath("get").With(getElement => + { + getElement.Should().HaveProperty("summary", "Retrieves the related space identities of an individual skyscraper's spaces relationship."); + + getElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related space identities to retrieve."); + }); + + getElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "Successfully returns the found space identities, or an empty array if none were found."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("head").With(headElement => + { + headElement.Should().HaveProperty("summary", "Retrieves the related space identities of an individual skyscraper's spaces relationship without returning them."); + headElement.Should().HaveProperty("description", "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched."); + + headElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose related space identities to retrieve."); + }); + + headElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(2); + responseElement.Should().HaveProperty("200.description", "The operation completed successfully."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + }); + }); + + skyscrapersElement.Should().ContainPath("post").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Adds existing spaces to the spaces relationship of an individual skyscraper."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to add spaces to."); + }); + + patchElement.Should().HaveProperty("requestBody.description", "The identities of the spaces to add to the spaces relationship."); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(4); + responseElement.Should().HaveProperty("204.description", "The spaces were successfully added, which did not result in additional changes."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible."); + }); + }); + + skyscrapersElement.Should().ContainPath("patch").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Assigns existing spaces to the spaces relationship of an individual skyscraper."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper whose spaces relationship to assign."); + }); + + patchElement.Should().HaveProperty("requestBody.description", "The identities of the spaces to assign to the spaces relationship, or an empty array to clear the relationship."); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(4); + responseElement.Should().HaveProperty("204.description", "The spaces relationship was successfully updated, which did not result in additional changes."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible."); + }); + }); + + skyscrapersElement.Should().ContainPath("delete").With(patchElement => + { + patchElement.Should().HaveProperty("summary", "Removes existing spaces from the spaces relationship of an individual skyscraper."); + + patchElement.Should().ContainPath("parameters").With(parametersElement => + { + parametersElement.EnumerateArray().ShouldHaveCount(1); + parametersElement.Should().HaveProperty("[0].description", "The identifier of the skyscraper to remove spaces from."); + }); + + patchElement.Should().HaveProperty("requestBody.description", "The identities of the spaces to remove from the spaces relationship."); + + patchElement.Should().ContainPath("responses").With(responseElement => + { + responseElement.EnumerateObject().ShouldHaveCount(4); + responseElement.Should().HaveProperty("204.description", "The spaces were successfully removed, which did not result in additional changes."); + responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist."); + responseElement.Should().HaveProperty("400.description", "The request body is missing or malformed."); + responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible."); + }); + }); + }); + } + + [Fact] + public async Task Resource_types_are_documented() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("components.schemas").With(schemasElement => + { + schemasElement.Should().HaveProperty("elevatorDataInPatchRequest.description", "An elevator within a skyscraper."); + schemasElement.Should().HaveProperty("elevatorDataInPostRequest.description", "An elevator within a skyscraper."); + schemasElement.Should().HaveProperty("elevatorDataInResponse.description", "An elevator within a skyscraper."); + + schemasElement.Should().HaveProperty("skyscraperDataInPatchRequest.description", "A tall, continuously habitable building having multiple floors."); + schemasElement.Should().HaveProperty("skyscraperDataInPostRequest.description", "A tall, continuously habitable building having multiple floors."); + schemasElement.Should().HaveProperty("skyscraperDataInResponse.description", "A tall, continuously habitable building having multiple floors."); + + schemasElement.Should().HaveProperty("spaceDataInPatchRequest.description", "A space within a skyscraper, such as an office, hotel, residential space, or retail space."); + schemasElement.Should().HaveProperty("spaceDataInPostRequest.description", "A space within a skyscraper, such as an office, hotel, residential space, or retail space."); + schemasElement.Should().HaveProperty("spaceDataInResponse.description", "A space within a skyscraper, such as an office, hotel, residential space, or retail space."); + }); + } + + [Fact] + public async Task Resource_attributes_are_documented() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("components.schemas").With(schemasElement => + { + schemasElement.Should().HaveProperty("elevatorAttributesInPatchRequest.properties.floorCount.description", "The number of floors this elevator provides access to."); + schemasElement.Should().HaveProperty("elevatorAttributesInPostRequest.properties.floorCount.description", "The number of floors this elevator provides access to."); + schemasElement.Should().HaveProperty("elevatorAttributesInResponse.properties.floorCount.description", "The number of floors this elevator provides access to."); + + schemasElement.Should().HaveProperty("skyscraperAttributesInPatchRequest.properties.heightInMeters.description", "The height of this building, in meters."); + schemasElement.Should().HaveProperty("skyscraperAttributesInPostRequest.properties.heightInMeters.description", "The height of this building, in meters."); + schemasElement.Should().HaveProperty("skyscraperAttributesInResponse.properties.heightInMeters.description", "The height of this building, in meters."); + + schemasElement.Should().HaveProperty("spaceAttributesInPatchRequest.properties.floorNumber.description", "The floor number on which this space resides."); + schemasElement.Should().HaveProperty("spaceAttributesInPostRequest.properties.floorNumber.description", "The floor number on which this space resides."); + schemasElement.Should().HaveProperty("spaceAttributesInResponse.properties.floorNumber.description", "The floor number on which this space resides."); + }); + } + + [Fact] + public async Task Enums_are_documented() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("components.schemas").With(schemasElement => + { + schemasElement.Should().HaveProperty("spaceKind.description", "Lists the various kinds of spaces within a skyscraper."); + }); + } + + [Fact] + public async Task Forbidden_status_is_added_when_client_generated_IDs_are_disabled() + { + // Act + JsonElement document = await _testContext.GetSwaggerDocumentAsync(); + + // Assert + document.Should().ContainPath("paths./elevators.post.responses").With(responseElement => + { + responseElement.Should().HaveProperty("403.description", "Client-generated IDs cannot be used at this endpoint."); + }); + } +} diff --git a/test/OpenApiTests/DocComments/Elevator.cs b/test/OpenApiTests/DocComments/Elevator.cs new file mode 100644 index 0000000000..6eb7af4e4b --- /dev/null +++ b/test/OpenApiTests/DocComments/Elevator.cs @@ -0,0 +1,26 @@ +using JetBrains.Annotations; +using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Resources; +using JsonApiDotNetCore.Resources.Annotations; + +namespace OpenApiTests.DocComments; + +/// +/// An elevator within a skyscraper. +/// +[UsedImplicitly(ImplicitUseTargetFlags.Members)] +[Resource(ControllerNamespace = "OpenApiTests.DocComments", ClientIdGeneration = ClientIdGenerationMode.Forbidden)] +public sealed class Elevator : Identifiable +{ + /// + /// The number of floors this elevator provides access to. + /// + [Attr] + public int FloorCount { get; set; } + + /// + /// The skyscraper this elevator exists in. + /// + [HasOne] + public Skyscraper ExistsIn { get; set; } = null!; +} diff --git a/test/OpenApiTests/DocComments/Skyscraper.cs b/test/OpenApiTests/DocComments/Skyscraper.cs new file mode 100644 index 0000000000..abbf06be80 --- /dev/null +++ b/test/OpenApiTests/DocComments/Skyscraper.cs @@ -0,0 +1,33 @@ +using System.ComponentModel.DataAnnotations; +using JetBrains.Annotations; +using JsonApiDotNetCore.Resources; +using JsonApiDotNetCore.Resources.Annotations; + +namespace OpenApiTests.DocComments; + +/// +/// A tall, continuously habitable building having multiple floors. +/// +[UsedImplicitly(ImplicitUseTargetFlags.Members)] +[Resource(ControllerNamespace = "OpenApiTests.DocComments")] +public sealed class Skyscraper : Identifiable +{ + /// + /// The height of this building, in meters. + /// + [Attr] + [Required] + public int? HeightInMeters { get; set; } + + /// + /// An optional elevator within this building, providing access to spaces. + /// + [HasOne] + public Elevator? Elevator { get; set; } + + /// + /// The spaces within this building. + /// + [HasMany] + public ISet Spaces { get; set; } = new HashSet(); +} diff --git a/test/OpenApiTests/DocComments/Space.cs b/test/OpenApiTests/DocComments/Space.cs new file mode 100644 index 0000000000..f4ba214b61 --- /dev/null +++ b/test/OpenApiTests/DocComments/Space.cs @@ -0,0 +1,31 @@ +using JetBrains.Annotations; +using JsonApiDotNetCore.Resources; +using JsonApiDotNetCore.Resources.Annotations; + +namespace OpenApiTests.DocComments; + +/// +/// A space within a skyscraper, such as an office, hotel, residential space, or retail space. +/// +[UsedImplicitly(ImplicitUseTargetFlags.Members)] +[Resource(ControllerNamespace = "OpenApiTests.DocComments")] +public sealed class Space : Identifiable +{ + /// + /// The floor number on which this space resides. + /// + [Attr] + public int FloorNumber { get; set; } + + /// + /// The kind of this space. + /// + [Attr] + public SpaceKind Kind { get; set; } + + /// + /// The skyscraper this space exists in. + /// + [HasOne] + public Skyscraper ExistsIn { get; set; } = null!; +} diff --git a/test/OpenApiTests/DocComments/SpaceKind.cs b/test/OpenApiTests/DocComments/SpaceKind.cs new file mode 100644 index 0000000000..bd3b0c3eca --- /dev/null +++ b/test/OpenApiTests/DocComments/SpaceKind.cs @@ -0,0 +1,15 @@ +using JetBrains.Annotations; + +namespace OpenApiTests.DocComments; + +/// +/// Lists the various kinds of spaces within a skyscraper. +/// +[UsedImplicitly(ImplicitUseTargetFlags.Members)] +public enum SpaceKind +{ + Office, + Hotel, + Residential, + Retail +} diff --git a/test/OpenApiTests/LegacyOpenApiIntegration/Airline.cs b/test/OpenApiTests/LegacyOpenApiIntegration/Airline.cs index f6004400c1..516d419388 100644 --- a/test/OpenApiTests/LegacyOpenApiIntegration/Airline.cs +++ b/test/OpenApiTests/LegacyOpenApiIntegration/Airline.cs @@ -2,6 +2,9 @@ namespace OpenApiTests.LegacyOpenApiIntegration; +/// +/// Lists the various airlines used in this API. +/// [UsedImplicitly(ImplicitUseTargetFlags.Members)] public enum Airline : byte { diff --git a/test/OpenApiTests/LegacyOpenApiIntegration/Airplane.cs b/test/OpenApiTests/LegacyOpenApiIntegration/Airplane.cs index c084edf5ee..8ecb055c59 100644 --- a/test/OpenApiTests/LegacyOpenApiIntegration/Airplane.cs +++ b/test/OpenApiTests/LegacyOpenApiIntegration/Airplane.cs @@ -23,6 +23,9 @@ public sealed class Airplane : Identifiable [Attr(Capabilities = AttrCapabilities.AllowView | AttrCapabilities.AllowCreate | AttrCapabilities.AllowChange)] public DateTime? LastServicedAt { get; set; } + /// + /// Gets the day on which this airplane was manufactured. + /// [Attr] public DateTime ManufacturedAt { get; set; } diff --git a/test/OpenApiTests/LegacyOpenApiIntegration/LegacyOpenApiIntegrationTests.cs b/test/OpenApiTests/LegacyOpenApiIntegration/LegacyOpenApiIntegrationTests.cs index a6da96f37b..e68f97fe0c 100644 --- a/test/OpenApiTests/LegacyOpenApiIntegration/LegacyOpenApiIntegrationTests.cs +++ b/test/OpenApiTests/LegacyOpenApiIntegration/LegacyOpenApiIntegrationTests.cs @@ -14,7 +14,7 @@ public LegacyOpenApiIntegrationTests() UseController(); UseController(); - SwaggerDocumentOutputPath = "test/OpenApiClientTests/LegacyClient"; + SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/LegacyClient"; } [Fact] diff --git a/test/OpenApiTests/LegacyOpenApiIntegration/swagger.json b/test/OpenApiTests/LegacyOpenApiIntegration/swagger.json index 83a045edbd..246cd45865 100644 --- a/test/OpenApiTests/LegacyOpenApiIntegration/swagger.json +++ b/test/OpenApiTests/LegacyOpenApiIntegration/swagger.json @@ -10,10 +10,11 @@ "tags": [ "airplanes" ], + "summary": "Retrieves a collection of airplanes.", "operationId": "get-airplane-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found airplanes, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -28,17 +29,12 @@ "tags": [ "airplanes" ], + "summary": "Retrieves a collection of airplanes without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/airplane-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -46,8 +42,10 @@ "tags": [ "airplanes" ], + "summary": "Creates a new airplane.", "operationId": "post-airplane", "requestBody": { + "description": "The attributes and relationships of the airplane to create.", "content": { "application/vnd.api+json": { "schema": { @@ -58,7 +56,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The airplane was successfully created, which resulted in additional changes. The newly created airplane is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -68,7 +66,19 @@ } }, "204": { - "description": "No Content" + "description": "The airplane was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -78,11 +88,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves an individual airplane by its identifier.", "operationId": "get-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to retrieve.", "required": true, "schema": { "type": "string" @@ -91,7 +103,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found airplane.", "content": { "application/vnd.api+json": { "schema": { @@ -99,6 +111,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -106,11 +121,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves an individual airplane by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to retrieve.", "required": true, "schema": { "type": "string" @@ -119,14 +137,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/airplane-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -134,11 +148,13 @@ "tags": [ "airplanes" ], + "summary": "Updates an existing airplane.", "operationId": "patch-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to update.", "required": true, "schema": { "type": "string" @@ -146,6 +162,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the airplane to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -156,7 +173,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The airplane was successfully updated, which resulted in additional changes. The updated airplane is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -166,7 +183,19 @@ } }, "204": { - "description": "No Content" + "description": "The airplane was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The airplane or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -174,11 +203,13 @@ "tags": [ "airplanes" ], + "summary": "Deletes an existing airplane by its identifier.", "operationId": "delete-airplane", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to delete.", "required": true, "schema": { "type": "string" @@ -187,7 +218,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The airplane was successfully deleted." + }, + "404": { + "description": "The airplane does not exist." } } } @@ -197,11 +231,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flights of an individual airplane's flights relationship.", "operationId": "get-airplane-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -210,7 +246,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -218,6 +254,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -225,11 +264,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flights of an individual airplane's flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -238,14 +280,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } } @@ -255,11 +293,13 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flight identities of an individual airplane's flights relationship.", "operationId": "get-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -268,7 +308,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -276,6 +316,9 @@ } } } + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -283,11 +326,14 @@ "tags": [ "airplanes" ], + "summary": "Retrieves the related flight identities of an individual airplane's flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -296,14 +342,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The airplane does not exist." } } }, @@ -311,11 +353,13 @@ "tags": [ "airplanes" ], + "summary": "Adds existing flights to the flights relationship of an individual airplane.", "operationId": "post-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to add flights to.", "required": true, "schema": { "type": "string" @@ -323,6 +367,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -333,7 +378,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -341,11 +395,13 @@ "tags": [ "airplanes" ], + "summary": "Assigns existing flights to the flights relationship of an individual airplane.", "operationId": "patch-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane whose flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -353,6 +409,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -363,7 +420,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -371,11 +437,13 @@ "tags": [ "airplanes" ], + "summary": "Removes existing flights from the flights relationship of an individual airplane.", "operationId": "delete-airplane-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the airplane to remove flights from.", "required": true, "schema": { "type": "string" @@ -383,6 +451,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -393,7 +462,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The airplane does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -403,10 +481,11 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves a collection of flight-attendants.", "operationId": "get-flight-attendant-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendants, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -421,17 +500,12 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves a collection of flight-attendants without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -439,8 +513,10 @@ "tags": [ "flight-attendants" ], + "summary": "Creates a new flight-attendant.", "operationId": "post-flight-attendant", "requestBody": { + "description": "The attributes and relationships of the flight-attendant to create.", "content": { "application/vnd.api+json": { "schema": { @@ -451,7 +527,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The flight-attendant was successfully created, which resulted in additional changes. The newly created flight-attendant is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -461,7 +537,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight-attendant was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -471,11 +559,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves an individual flight-attendant by its identifier.", "operationId": "get-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -484,7 +574,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant.", "content": { "application/vnd.api+json": { "schema": { @@ -492,6 +582,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -499,11 +592,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves an individual flight-attendant by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -512,14 +608,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -527,11 +619,13 @@ "tags": [ "flight-attendants" ], + "summary": "Updates an existing flight-attendant.", "operationId": "patch-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to update.", "required": true, "schema": { "type": "string" @@ -539,6 +633,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the flight-attendant to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -549,7 +644,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The flight-attendant was successfully updated, which resulted in additional changes. The updated flight-attendant is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -559,7 +654,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight-attendant was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -567,11 +674,13 @@ "tags": [ "flight-attendants" ], + "summary": "Deletes an existing flight-attendant by its identifier.", "operationId": "delete-flight-attendant", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to delete.", "required": true, "schema": { "type": "string" @@ -580,7 +689,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The flight-attendant was successfully deleted." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -590,11 +702,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's purser-on-flights relationship.", "operationId": "get-flight-attendant-purser-on-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -603,7 +717,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -611,6 +725,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -618,11 +735,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's purser-on-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-purser-on-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -631,14 +751,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -648,11 +764,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's purser-on-flights relationship.", "operationId": "get-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -661,7 +779,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -669,6 +787,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -676,11 +797,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's purser-on-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -689,14 +813,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -704,11 +824,13 @@ "tags": [ "flight-attendants" ], + "summary": "Adds existing flights to the purser-on-flights relationship of an individual flight-attendant.", "operationId": "post-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to add flights to.", "required": true, "schema": { "type": "string" @@ -716,6 +838,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the purser-on-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -726,7 +849,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -734,11 +866,13 @@ "tags": [ "flight-attendants" ], + "summary": "Assigns existing flights to the purser-on-flights relationship of an individual flight-attendant.", "operationId": "patch-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose purser-on-flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -746,6 +880,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the purser-on-flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -756,7 +891,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The purser-on-flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -764,11 +908,13 @@ "tags": [ "flight-attendants" ], + "summary": "Removes existing flights from the purser-on-flights relationship of an individual flight-attendant.", "operationId": "delete-flight-attendant-purser-on-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to remove flights from.", "required": true, "schema": { "type": "string" @@ -776,6 +922,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the purser-on-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -786,7 +933,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -796,11 +952,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's scheduled-for-flights relationship.", "operationId": "get-flight-attendant-scheduled-for-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -809,7 +967,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -817,6 +975,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -824,11 +985,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flights of an individual flight-attendant's scheduled-for-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-scheduled-for-flights", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flights to retrieve.", "required": true, "schema": { "type": "string" @@ -837,14 +1001,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } } @@ -854,11 +1014,13 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's scheduled-for-flights relationship.", "operationId": "get-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -867,7 +1029,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -875,6 +1037,9 @@ } } } + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -882,11 +1047,14 @@ "tags": [ "flight-attendants" ], + "summary": "Retrieves the related flight identities of an individual flight-attendant's scheduled-for-flights relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose related flight identities to retrieve.", "required": true, "schema": { "type": "string" @@ -895,14 +1063,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight-attendant does not exist." } } }, @@ -910,11 +1074,13 @@ "tags": [ "flight-attendants" ], + "summary": "Adds existing flights to the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "post-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to add flights to.", "required": true, "schema": { "type": "string" @@ -922,6 +1088,7 @@ } ], "requestBody": { + "description": "The identities of the flights to add to the scheduled-for-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -932,7 +1099,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -940,11 +1116,13 @@ "tags": [ "flight-attendants" ], + "summary": "Assigns existing flights to the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "patch-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant whose scheduled-for-flights relationship to assign.", "required": true, "schema": { "type": "string" @@ -952,6 +1130,7 @@ } ], "requestBody": { + "description": "The identities of the flights to assign to the scheduled-for-flights relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -962,7 +1141,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The scheduled-for-flights relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -970,11 +1158,13 @@ "tags": [ "flight-attendants" ], + "summary": "Removes existing flights from the scheduled-for-flights relationship of an individual flight-attendant.", "operationId": "delete-flight-attendant-scheduled-for-flights-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight-attendant to remove flights from.", "required": true, "schema": { "type": "string" @@ -982,6 +1172,7 @@ } ], "requestBody": { + "description": "The identities of the flights to remove from the scheduled-for-flights relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -992,7 +1183,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flights were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight-attendant does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1002,10 +1202,11 @@ "tags": [ "flights" ], + "summary": "Retrieves a collection of flights.", "operationId": "get-flight-collection", "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flights, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1020,17 +1221,12 @@ "tags": [ "flights" ], + "summary": "Retrieves a collection of flights without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-collection", "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-collection-response-document" - } - } - } + "description": "The operation completed successfully." } } }, @@ -1038,8 +1234,10 @@ "tags": [ "flights" ], + "summary": "Creates a new flight.", "operationId": "post-flight", "requestBody": { + "description": "The attributes and relationships of the flight to create.", "content": { "application/vnd.api+json": { "schema": { @@ -1050,7 +1248,7 @@ }, "responses": { "201": { - "description": "Created", + "description": "The flight was successfully created, which resulted in additional changes. The newly created flight is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -1060,7 +1258,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight was successfully created, which did not result in additional changes." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." + }, + "403": { + "description": "Client-generated IDs cannot be used at this endpoint." } } } @@ -1070,11 +1280,13 @@ "tags": [ "flights" ], + "summary": "Retrieves an individual flight by its identifier.", "operationId": "get-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to retrieve.", "required": true, "schema": { "type": "string" @@ -1083,7 +1295,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight.", "content": { "application/vnd.api+json": { "schema": { @@ -1091,6 +1303,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1098,11 +1313,14 @@ "tags": [ "flights" ], + "summary": "Retrieves an individual flight by its identifier without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to retrieve.", "required": true, "schema": { "type": "string" @@ -1111,14 +1329,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-primary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1126,11 +1340,13 @@ "tags": [ "flights" ], + "summary": "Updates an existing flight.", "operationId": "patch-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to update.", "required": true, "schema": { "type": "string" @@ -1138,6 +1354,7 @@ } ], "requestBody": { + "description": "The attributes and relationships of the flight to update. Omitted fields are left unchanged.", "content": { "application/vnd.api+json": { "schema": { @@ -1148,7 +1365,7 @@ }, "responses": { "200": { - "description": "Success", + "description": "The flight was successfully updated, which resulted in additional changes. The updated flight is returned.", "content": { "application/vnd.api+json": { "schema": { @@ -1158,7 +1375,19 @@ } }, "204": { - "description": "No Content" + "description": "The flight was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight or a related resource does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type or identifier in the request body is incompatible." + }, + "422": { + "description": "Validation of the request body failed." } } }, @@ -1166,11 +1395,13 @@ "tags": [ "flights" ], + "summary": "Deletes an existing flight by its identifier.", "operationId": "delete-flight", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to delete.", "required": true, "schema": { "type": "string" @@ -1179,7 +1410,10 @@ ], "responses": { "204": { - "description": "No Content" + "description": "The flight was successfully deleted." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1189,11 +1423,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's backup-purser relationship.", "operationId": "get-flight-backup-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1202,7 +1438,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1210,6 +1446,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1217,11 +1456,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's backup-purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-backup-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1230,14 +1472,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-flight-attendant-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1247,11 +1485,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's backup-purser relationship.", "operationId": "get-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1260,7 +1500,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1268,6 +1508,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1275,11 +1518,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's backup-purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1288,14 +1534,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/nullable-flight-attendant-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1303,11 +1545,13 @@ "tags": [ "flights" ], + "summary": "Clears or assigns an existing flight-attendant to the backup-purser relationship of an individual flight.", "operationId": "patch-flight-backup-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose backup-purser relationship to assign or clear.", "required": true, "schema": { "type": "string" @@ -1315,6 +1559,7 @@ } ], "requestBody": { + "description": "The identity of the flight-attendant to assign to the backup-purser relationship, or `null` to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1325,7 +1570,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The backup-purser relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1335,11 +1589,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendants of an individual flight's cabin-crew-members relationship.", "operationId": "get-flight-cabin-crew-members", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendants to retrieve.", "required": true, "schema": { "type": "string" @@ -1348,7 +1604,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendants, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1356,6 +1612,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1363,11 +1622,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendants of an individual flight's cabin-crew-members relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-cabin-crew-members", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendants to retrieve.", "required": true, "schema": { "type": "string" @@ -1376,14 +1638,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1393,11 +1651,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identities of an individual flight's cabin-crew-members relationship.", "operationId": "get-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1406,7 +1666,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1414,6 +1674,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1421,11 +1684,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identities of an individual flight's cabin-crew-members relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1434,14 +1700,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1449,11 +1711,13 @@ "tags": [ "flights" ], + "summary": "Adds existing flight-attendants to the cabin-crew-members relationship of an individual flight.", "operationId": "post-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to add flight-attendants to.", "required": true, "schema": { "type": "string" @@ -1461,6 +1725,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to add to the cabin-crew-members relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1471,7 +1736,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flight-attendants were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1479,11 +1753,13 @@ "tags": [ "flights" ], + "summary": "Assigns existing flight-attendants to the cabin-crew-members relationship of an individual flight.", "operationId": "patch-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose cabin-crew-members relationship to assign.", "required": true, "schema": { "type": "string" @@ -1491,6 +1767,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to assign to the cabin-crew-members relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1501,7 +1778,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The cabin-crew-members relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1509,11 +1795,13 @@ "tags": [ "flights" ], + "summary": "Removes existing flight-attendants from the cabin-crew-members relationship of an individual flight.", "operationId": "delete-flight-cabin-crew-members-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to remove flight-attendants from.", "required": true, "schema": { "type": "string" @@ -1521,6 +1809,7 @@ } ], "requestBody": { + "description": "The identities of the flight-attendants to remove from the cabin-crew-members relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1531,7 +1820,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The flight-attendants were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1541,11 +1839,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passengers of an individual flight's passengers relationship.", "operationId": "get-flight-passengers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passengers to retrieve.", "required": true, "schema": { "type": "string" @@ -1554,7 +1854,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found passengers, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1562,6 +1862,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1569,11 +1872,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passengers of an individual flight's passengers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-passengers", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passengers to retrieve.", "required": true, "schema": { "type": "string" @@ -1582,14 +1888,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/passenger-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1599,11 +1901,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passenger identities of an individual flight's passengers relationship.", "operationId": "get-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passenger identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1612,7 +1916,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found passenger identities, or an empty array if none were found.", "content": { "application/vnd.api+json": { "schema": { @@ -1620,6 +1924,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1627,11 +1934,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related passenger identities of an individual flight's passengers relationship without returning them.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related passenger identities to retrieve.", "required": true, "schema": { "type": "string" @@ -1640,14 +1950,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/passenger-identifier-collection-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1655,11 +1961,13 @@ "tags": [ "flights" ], + "summary": "Adds existing passengers to the passengers relationship of an individual flight.", "operationId": "post-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to add passengers to.", "required": true, "schema": { "type": "string" @@ -1667,6 +1975,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to add to the passengers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1677,7 +1986,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers were successfully added, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1685,11 +2003,13 @@ "tags": [ "flights" ], + "summary": "Assigns existing passengers to the passengers relationship of an individual flight.", "operationId": "patch-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose passengers relationship to assign.", "required": true, "schema": { "type": "string" @@ -1697,6 +2017,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to assign to the passengers relationship, or an empty array to clear the relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1707,7 +2028,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } }, @@ -1715,11 +2045,13 @@ "tags": [ "flights" ], + "summary": "Removes existing passengers from the passengers relationship of an individual flight.", "operationId": "delete-flight-passengers-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight to remove passengers from.", "required": true, "schema": { "type": "string" @@ -1727,6 +2059,7 @@ } ], "requestBody": { + "description": "The identities of the passengers to remove from the passengers relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1737,7 +2070,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The passengers were successfully removed, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1747,11 +2089,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's purser relationship.", "operationId": "get-flight-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1760,7 +2104,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1768,6 +2112,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1775,11 +2122,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant of an individual flight's purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-purser", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant to retrieve.", "required": true, "schema": { "type": "string" @@ -1788,14 +2138,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-secondary-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } } @@ -1805,11 +2151,13 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's purser relationship.", "operationId": "get-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1818,7 +2166,7 @@ ], "responses": { "200": { - "description": "Success", + "description": "Successfully returns the found flight-attendant identity, or `null` if it was not found.", "content": { "application/vnd.api+json": { "schema": { @@ -1826,6 +2174,9 @@ } } } + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1833,11 +2184,14 @@ "tags": [ "flights" ], + "summary": "Retrieves the related flight-attendant identity of an individual flight's purser relationship without returning it.", + "description": "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.", "operationId": "head-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose related flight-attendant identity to retrieve.", "required": true, "schema": { "type": "string" @@ -1846,14 +2200,10 @@ ], "responses": { "200": { - "description": "Success", - "content": { - "application/vnd.api+json": { - "schema": { - "$ref": "#/components/schemas/flight-attendant-identifier-response-document" - } - } - } + "description": "The operation completed successfully." + }, + "404": { + "description": "The flight does not exist." } } }, @@ -1861,11 +2211,13 @@ "tags": [ "flights" ], + "summary": "Assigns an existing flight-attendant to the purser relationship of an individual flight.", "operationId": "patch-flight-purser-relationship", "parameters": [ { "name": "id", "in": "path", + "description": "The identifier of the flight whose purser relationship to assign.", "required": true, "schema": { "type": "string" @@ -1873,6 +2225,7 @@ } ], "requestBody": { + "description": "The identity of the flight-attendant to assign to the purser relationship.", "content": { "application/vnd.api+json": { "schema": { @@ -1883,7 +2236,16 @@ }, "responses": { "204": { - "description": "No Content" + "description": "The purser relationship was successfully updated, which did not result in additional changes." + }, + "404": { + "description": "The flight does not exist." + }, + "400": { + "description": "The request body is missing or malformed." + }, + "409": { + "description": "A resource type in the request body is incompatible." } } } @@ -1906,7 +2268,8 @@ "LufthansaGroup", "AirFranceKlm" ], - "type": "string" + "type": "string", + "description": "Lists the various airlines used in this API." }, "airplane-attributes-in-patch-request": { "type": "object", @@ -1996,6 +2359,7 @@ }, "manufactured-at": { "type": "string", + "description": "Gets the day on which this airplane was manufactured.", "format": "date-time" }, "is-in-maintenance": { diff --git a/test/OpenApiTests/NamingConventions/CamelCase/CamelCaseTests.cs b/test/OpenApiTests/NamingConventions/CamelCase/CamelCaseTests.cs index 9a694feab5..cd786b26b8 100644 --- a/test/OpenApiTests/NamingConventions/CamelCase/CamelCaseTests.cs +++ b/test/OpenApiTests/NamingConventions/CamelCase/CamelCaseTests.cs @@ -13,7 +13,7 @@ public CamelCaseTests(OpenApiTestContext(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/NamingConventions/CamelCase"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/NamingConventions/CamelCase"; } [Fact] diff --git a/test/OpenApiTests/NamingConventions/KebabCase/KebabCaseTests.cs b/test/OpenApiTests/NamingConventions/KebabCase/KebabCaseTests.cs index e0447fc482..628576679b 100644 --- a/test/OpenApiTests/NamingConventions/KebabCase/KebabCaseTests.cs +++ b/test/OpenApiTests/NamingConventions/KebabCase/KebabCaseTests.cs @@ -13,7 +13,7 @@ public KebabCaseTests(OpenApiTestContext(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/NamingConventions/KebabCase"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/NamingConventions/KebabCase"; } [Fact] diff --git a/test/OpenApiTests/NamingConventions/PascalCase/PascalCaseTests.cs b/test/OpenApiTests/NamingConventions/PascalCase/PascalCaseTests.cs index 48497186c5..cd04ad8565 100644 --- a/test/OpenApiTests/NamingConventions/PascalCase/PascalCaseTests.cs +++ b/test/OpenApiTests/NamingConventions/PascalCase/PascalCaseTests.cs @@ -14,7 +14,7 @@ public PascalCaseTests(OpenApiTestContext(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/NamingConventions/PascalCase"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/NamingConventions/PascalCase"; } [Fact] diff --git a/test/OpenApiTests/OpenApiStartup.cs b/test/OpenApiTests/OpenApiStartup.cs index e34ed1894c..6affd0bacc 100644 --- a/test/OpenApiTests/OpenApiStartup.cs +++ b/test/OpenApiTests/OpenApiStartup.cs @@ -1,7 +1,9 @@ +using System.Reflection; using JsonApiDotNetCore.Configuration; using JsonApiDotNetCore.OpenApi; using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; +using Swashbuckle.AspNetCore.SwaggerGen; using TestBuildingBlocks; namespace OpenApiTests; @@ -15,7 +17,13 @@ public override void ConfigureServices(IServiceCollection services) services.AddJsonApi(SetJsonApiOptions, mvcBuilder: mvcBuilder); - services.AddOpenApi(mvcBuilder); + services.AddOpenApi(mvcBuilder, SetupSwaggerGenAction); + } + + protected virtual void SetupSwaggerGenAction(SwaggerGenOptions options) + { + string documentationPath = Path.ChangeExtension(Assembly.GetExecutingAssembly().Location, ".xml"); + options.IncludeXmlComments(documentationPath); } public override void Configure(IApplicationBuilder app) diff --git a/test/OpenApiTests/OpenApiTestContext.cs b/test/OpenApiTests/OpenApiTestContext.cs index e54d09a269..e09f801bac 100644 --- a/test/OpenApiTests/OpenApiTestContext.cs +++ b/test/OpenApiTests/OpenApiTestContext.cs @@ -12,7 +12,7 @@ public class OpenApiTestContext : IntegrationTestContext> _lazySwaggerDocument; - internal string? SwaggerDocumentOutputPath { private get; set; } + internal string? SwaggerDocumentOutputDirectory { private get; set; } public OpenApiTestContext() { @@ -30,9 +30,9 @@ private async Task CreateSwaggerDocumentAsync() JsonElement rootElement = ParseSwaggerDocument(content); - if (SwaggerDocumentOutputPath != null) + if (SwaggerDocumentOutputDirectory != null) { - string absoluteOutputPath = GetSwaggerDocumentAbsoluteOutputPath(SwaggerDocumentOutputPath); + string absoluteOutputPath = GetSwaggerDocumentAbsoluteOutputPath(SwaggerDocumentOutputDirectory); await WriteToDiskAsync(absoluteOutputPath, rootElement); } diff --git a/test/OpenApiTests/OpenApiTests.csproj b/test/OpenApiTests/OpenApiTests.csproj index 32ea69850c..24a6eba897 100644 --- a/test/OpenApiTests/OpenApiTests.csproj +++ b/test/OpenApiTests/OpenApiTests.csproj @@ -1,6 +1,8 @@ $(TargetFrameworkName) + True + $(NoWarn);1591 diff --git a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/NullabilityTests.cs b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/NullabilityTests.cs index d02338445e..0e0779daf3 100644 --- a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/NullabilityTests.cs +++ b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff/NullabilityTests.cs @@ -14,7 +14,7 @@ public NullabilityTests(OpenApiTestContext, NrtOf _testContext = testContext; testContext.UseController(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOff"; } [Theory] diff --git a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/NullabilityTests.cs b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/NullabilityTests.cs index 185cd9a5e1..e5171495f4 100644 --- a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/NullabilityTests.cs +++ b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn/NullabilityTests.cs @@ -14,7 +14,7 @@ public NullabilityTests(OpenApiTestContext, NrtO _testContext = testContext; testContext.UseController(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOff/ModelStateValidationOn"; } [Theory] diff --git a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/NullabilityTests.cs b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/NullabilityTests.cs index a41c3f7508..f497022c6d 100644 --- a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/NullabilityTests.cs +++ b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff/NullabilityTests.cs @@ -14,7 +14,7 @@ public NullabilityTests(OpenApiTestContext, NrtOnD _testContext = testContext; testContext.UseController(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOff"; } [Theory] diff --git a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/NullabilityTests.cs b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/NullabilityTests.cs index 2d1cf8c117..7062bddaab 100644 --- a/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/NullabilityTests.cs +++ b/test/OpenApiTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn/NullabilityTests.cs @@ -14,7 +14,7 @@ public NullabilityTests(OpenApiTestContext, NrtOn _testContext = testContext; testContext.UseController(); - testContext.SwaggerDocumentOutputPath = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn"; + testContext.SwaggerDocumentOutputDirectory = "test/OpenApiClientTests/ResourceFieldValidation/NullableReferenceTypesOn/ModelStateValidationOn"; } [Theory] diff --git a/test/TestBuildingBlocks/JsonElementAssertionExtensions.cs b/test/TestBuildingBlocks/JsonElementAssertionExtensions.cs index b541c46754..e53117ff23 100644 --- a/test/TestBuildingBlocks/JsonElementAssertionExtensions.cs +++ b/test/TestBuildingBlocks/JsonElementAssertionExtensions.cs @@ -116,6 +116,11 @@ public void Be(object? value) } } + public void HaveProperty(string propertyName, string propertyValue) + { + _subject.Should().ContainPath(propertyName).With(element => element.Should().Be(propertyValue)); + } + public void ContainArrayElement(string value) { _subject.ValueKind.Should().Be(JsonValueKind.Array);