Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI: Use allOf for complex types #1372

Merged
merged 2 commits into from
Oct 27, 2023
Merged

OpenAPI: Use allOf for complex types #1372

merged 2 commits into from
Oct 27, 2023

Conversation

bkoelman
Copy link
Member

@bkoelman bkoelman commented Oct 27, 2023

In OAS 3.0, a $ref element cannot be combined with other directives, such as nullable and description. The workaround is to wrap such elements in a single-element allOf array. For details, see OAI/OpenAPI-Specification#1514 and OAI/OpenAPI-Specification#1368. This limitation no longer applies in OAS 3.1, but there is no .NET implementation for that yet. Swashbuckle.AspNetCore is waiting for Microsoft to implement that in their object models (see domaindrivendev/Swashbuckle.AspNetCore#2349).

This PR introduces the use of allOf, which simplifies handling nullable references (it no longer emits the null-value component schema). All credits go to @maurei, I just rebased his work on the latest changes.

Additionally, this PR lifts the limitations on documenting relationships and enum-typed attributes.

QUALITY CHECKLIST

@bkoelman bkoelman changed the title OpenAPI: Use AllOf for complex types OpenAPI: Use allOf for complex types Oct 27, 2023
@codecov
Copy link

codecov bot commented Oct 27, 2023

Codecov Report

Merging #1372 (60b63db) into openapi (088fde5) will decrease coverage by 0.03%.
The diff coverage is 92.64%.

@@             Coverage Diff             @@
##           openapi    #1372      +/-   ##
===========================================
- Coverage    90.25%   90.23%   -0.03%     
===========================================
  Files          308      308              
  Lines        10137    10114      -23     
  Branches      1691     1692       +1     
===========================================
- Hits          9149     9126      -23     
+ Misses         653      651       -2     
- Partials       335      337       +2     
Files Coverage Δ
...iDotNetCore.OpenApi/ServiceCollectionExtensions.cs 95.77% <100.00%> (+0.06%) ⬆️
...penApi/SwaggerComponents/JsonApiSchemaGenerator.cs 100.00% <100.00%> (ø)
...SwaggerComponents/ResourceObjectSchemaGenerator.cs 100.00% <100.00%> (ø)
...i/SwaggerComponents/ResourceTypeSchemaGenerator.cs 100.00% <100.00%> (ø)
...onApiDotNetCore.OpenApi/OpenApiSchemaExtensions.cs 50.00% <50.00%> (ø)
...ggerComponents/ResourceFieldObjectSchemaBuilder.cs 96.77% <90.62%> (-2.30%) ⬇️

@bkoelman bkoelman marked this pull request as ready for review October 27, 2023 01:52
@bkoelman bkoelman merged commit 6f89ded into openapi Oct 27, 2023
14 checks passed
@bkoelman bkoelman deleted the openapi-allof branch October 27, 2023 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants