OAS 3.1 support?

[Kormyr]

Hello,

I just discovered this wonderful VSCode extension. Thank you for all the work on this.

OpenAPI Specification 3.1 has been released recently (https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0).
Are there already plans to implement it?

[ak1394]

Thanks! Happy you liked the extension. As for 3.1, we plan to support it of course. My guess it will not make it to the next release (which quite close to being published) but one after that.

[ak1394]

I had a closer look at the new spec, and it looks like there are some issues in around schema validation which might delay it a bit.

The JSON schema for 3.1 is WIP OAI/OpenAPI-Specification#2016 but once it's done it'll require 2019-09 schema support in VS Code microsoft/vscode#98724

[spacedsweden]

microsoft/vscode#98724 (comment)

Can we do yaml meanwhile?

[ak1394]

Nope, VS Code uses the same JSON Schema implementation for both YAML and JSON. You're linking to a comment mentioning some other non vs-code implementations of JSON Schema 2020-12, but that doesn't help much as we need VS Code one (which provides auto-completion, etc) to implement the new schema standard.

[amh4r]

Looking forward to 3.1.0 support! Your extension has been a fantastic guardrail for our new-to-OpenAPI engineers, but we have to start using 3.1.0 (to get proper nullable reference schemas: OAI/OpenAPI-Specification#1368)

[ak1394]

@goodoldneon thanks for the feedback! We would like to introduce 3.1 support as soon as we can, the main issue being 2019-09 schema support in VS Code...

[tforster]

I too have switched to 3.1.0 to take advantage of nullable reference schemas. Is it possible to make this extension work with another validator, at least until VSCode catches up?

[ak1394]

@tforster It's hard to do, because the built-in checker not only does validation but drives intellisence/completions as well.

[Guo-Zhang]

Hope that 3.1.0 can be supported! What are the difficulties?

[apkrieg]

Came looking for 3.1.0 support, found sadness. Can't wait for an update.

[spacedsweden]

Any news on this? is the spec stable enough now?

[tforster]

FWIW I have now switched over to Redocly using their free CLI. I am having no issues developing, building, linting and viewing OAS 3.1.0 schemas.

I use two NPM scripts, one to build and lint my schema and the other to open the schema in the Redocly viewer.

"scripts": {
  "buildSchemas": "npx @redocly/openapi-cli lint docs/rest-api/openapi.yaml; npx @redocly/openapi-cli bundle docs/rest-api/openapi.yaml --output src/rest.json",
  "showDocs": "xdg-open http://127.0.0.1:8080; npx @redocly/openapi-cli preview-docs docs/rest-api/openapi.yaml;"
},

[spacedsweden]

I have done the same, i am actually using their vs extension as well. however i do miss the sidepanel i get with 42crunch

[PhilParisot]

Any news? 3.1.0 has been out for a while now.

[ak1394]

Well, there seem to be some progress on implementing required schema support: microsoft/vscode#98724

As soon as it lands in VS Code, we'll start working on it.

[rubensa]

Have this fixed the impediment to get OAS 3.1 support?

[ak1394]

Nope, the issue to watch is the one I've linked above, it is still open.

[rubensa]

Nope, the issue to watch is the one I've linked above, it is still open.

Ok. Thanks for the clarification.

PS: So looks like the meta-schema support is the needed missing part.

[anikitin]

This plugin can use both Swagger UI and ReDoc to preview the spec. Swagger UI still doesn't support OAS 3.1 but ReDoc does.
Would be nice to have at least 3.1 support with only ReDoc implementation.

[defunctzombie]

Is there a way to patch the plugin so it will work with 3.1 spec files? Even if not all features are present?

[behrenle]

Any news on this topic?

[ak1394]

No news, there is not much happening in microsoft/vscode#98724 so we have to wait as well

[kkamath-bandwidth]

FYI. I was happily using the 42Crunch plugin, but this ended up being the forcing function to move to next option in VSCode marketplace. The ReDocly one forces you to use an apiKey for a simple preview, no thanks.

[spacedsweden]

What’s the problem using an api key?

[kkamath-bandwidth]

I did not want to go through the step of configuring it. So personal preference, and there is no problem.

[anywhereinfo]

We have a custom spectral file and redocly does not seem to support it.

[spacedsweden]

no you would need to port it to redoc linter

[cuttingclyde]

Swagger UI open source project released support for OAS 3.1 on 6-12-23, https://github.com/swagger-api/swagger-ui.

I'm not sure why you would also need to wait for VSCode support for JSON Schema 2020-12 validation in OAS 3.1, to simply support swagger.io preview of 3.1 versioned OAS documents. Can't they live separately? Only OAS 3.0 validation with OAS 3.1 preview?

[anywhereinfo]

For me, its important to have a editor with intellisense and schema validation for 3.1. Creation of OAS 3.1 document and Governance via Spectral Linter can be done without swagger preview. But if a tool can support all the use cases why not. So, i found stoplight studio, which is opensource, studio, supports 3.1 editing, intellisense and preview. Plus it leverages spectral linting, so my existing investment in rules can be ported without any change

[shreyasbharath]

Bump, any news on this please?

[kornicameister]

#242 got merged recently.
Does it mean we can get new tag in the air?

[ak1394]

I'll look at adding support for 3.1 for preview (which should be enabled by new SwaggerUI) but until microsoft/vscode#98724 is done, we won't have proper 3.1 support in the editor...

[terjew]

What is the status here, did you start working on a version supporting the 3.1 spec?

If I understand the discussion at microsoft/vscode#98724 correctly, the missing feature in vscode is now mostly implemented. I'd be fine with a limited autocomplete for instance, if the preview was able to work properly with the 3.1 spec.

[ak1394]

No, unfortunately there has been no progress on the vscode issue since May 2022. It could be that we'll have to do something about 3.1 support despite not having working schema support in VS Code, but I have no concrete time frame for it.

[sbeitzel]

So, as @terjew mentions above, it looks as though MS has decided to export all the JSON stuff to a separate language service microsoft/vscode-json-languageservice. The discussion on the perpetually linked issue seems to amount to various end users coming in with variants of, "Hey, this plugin I like doesn't work with modern JSON and it's because VS Code doesn't know how to use it? Can I haz fix?" and with the responsible developer saying, "There's no bug, here, and there's a language service so maybe the plugin or someone can go ask it for stuff?"

Anyway. I have no idea what a language service does (other than crash and require a restart when I put a typo in my source code) nor how easily a plugin like this one could consume such a service, nor even if that hypothetical interaction would solve our problems. But does anyone else reading this issue know?

[andreasvh-conceto]

Hi @sbeitzel
i am subscribed to this issue and still interested. Last week i had to create an OAS 3.1. I was forced to use the nextSwaggerEditor. JsonSchemaV4 is not enough. Still hoping for support from vscode, so that plugins like this will work with the newest standard.

[alexanderilyin]

THIMC: Solution for me was to move to https://huma.rocks/