add openapi 3.1 support #5372
Merged
add openapi 3.1 support #5372
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
) This PR adds a new `@typespec/openapi3` emitter option to support specifying which Open API 3.x specs to output. Currently marked as `@internal` since currently only 1 version is actually supported. Once `v3.1` is supported we can remove the `@internal` annotation. --------- Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
Related to #5009 and #5010 This PR starts the work of getting an Open API 3.1 emitter in the `@typespec/openapi3` package. There are a few changes introduced in this PR: 1. Added the `OpenAPIDocument3_1` and related types. The biggest change here is updating the Open API schema to be based on Json Schema 2020-12. The Json Schema types don't currently exist in `@typespec/json-schema` so I added them to `@typespec/openapi3` for now while iterating. Can move to `@typespec/json-schema` now or later if we want. 2. Created the OpenAPISchemaEmitter3_1 class to target Open API 3.1 schemas. Currently completely standalone from Json Schema and Open API 3.0 schema emitters. 3. Updated nearly all tests to now run against both Open API 3.x versions. Intentionally left out the enum tests and schema examples since those will be updated shortly and be different between the two versions. 4. Added support for `type: "null"` in the 3.1 schema emitter. I squeezed this change in because the changes involved were actually really small, and this way TypeScript was happy we were emitting 3.1 schemas that matched the defined interface (no `nullable`). I copied the behavior that the Json Schema emitter uses for handling nulls. 5. Updated `exclusiveMinimum/Maximum` to be a number value instead of a boolean to match the Open API 3.1 spec. Note to reviewers: Hide whitespace - otherwise the test changes will look monstrous. --------- Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
Implements #5013 Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
Implements #5011 The only place I found this made sense to emit a schema type as a list currently is with enums as mentioned in the linked issue. Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
|
All changed packages have been documented.
Show changes
|
|
You can try these changes here
|
chrisradek
requested review from
bterlson,
markcowl,
allenjzhang and
timotheeguerin
as code owners
wanlwanl
approved these changes
Dec 24, 2024
This was referenced Dec 27, 2024
Closed
This PR updates the `@typespec/openapi3` emitter to read state from the `@typespec/json-schema` decorators. --------- Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
This PR updates the playground to handle array emitter options. Currently this mainly supports options that are an array of enums - such as the new openapi3 versions option. If an option accepts an array of non-enums, then currently it will display a single input field, effectively restricting usage to a single element. As new array options come up we can decide how we want to display them (e.g. show a '+' sign and create a new element?) Screenshot of the `Openapi Versions` option showing both choices as selectable:  Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
Fixes #5507 This PR updates the Open API 3.1 schema to support binary types. The linked issue includes more details on the required changes (and Open API 3.1 spec) but here's a quick summary: ## Binary types Open API supports 2 types of binary data: raw (unencoded) binary, and encoded binary. In Open API 3.0, binary data is described using the `string` type with `format: binary` indicating raw binary data, and `format: byte` indicating encoded binary data (defaulted to base64 encoding). In Open API 3.1, binary data is represented with an empty schema - `{}` for raw binary data, and uses the `string` type with `contentEncoding: base64` to represent encoded binary data (note that the actual value of contentEncoding can be anything). Additionally, `contentMediaType` can be set on both raw and encoded binary data schemas, though this value will be ignored if `encoding` fields are present (common for multipart) or if it matches the requestBody content type. This PR preserves the behavior where `@encode` can be used to indicate the content encoding. For Open API 3.0, it updates the encoded binary schema's `format` field. In Open API 3.1, it will update the encoded binary schema's `contentEncoding` field. --------- Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
witemple-msft
approved these changes
Jan 14, 2025
There was a problem hiding this comment.
To summarize:
- I don't have a ton of context here, but I understand that everything has been reviewed once already prior to being merged into this branch, and this is to merge the feature branch into main.
- The 3.0-specific code has been removed from the base implementation of the spec emitter, and reimplemented as a subclass of the base emitter that is nearly-identical for the 3.0 emitter.
- You get a copy of the emitter per OpenAPI version selected in the options, which can be one of 3.0, 3.1, both, or neither.
- The user must affirmatively opt in to 3.1 support.
Given this, I don't see much risk to existing 3.0 users. I have some comments on the options and stubbed implementations in the base emitter, but overall with the implementation having been previously reviewed I'm good with it. I do think it's worth adding some defensive checks against weird version configurations (empty, same version multiple times) unless I missed where that's done, and it might be worth replacing simple throw new Error("not implemented") with compilerAssert(false, "Unreachable: virtual method XYZ not overridden") for those stub implementations that MUST be overridden by the base emitter subclasses. But that's more for our own benefit so that someone looking at the code knows why it throws an error and what needs to be done to fix it.
This was referenced Jan 17, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds support for Open API 3.1 in the
@typespec/openapi3package.The changes in this PR includes:
#4946 - adds
output-spec-versionsemitter option#5035 - adds initial open api 3.1 schema emitter
#5245 - add support for tuples
#5246 - add support for enums backed by multiple types
#5310 - playground support for array of constants emitter options
#5407 - add support for json-schema decorators
#5549 - add support for binary types in Open API 3.1