OpenAPITools / OpenAPITools/openapi-generator

[REQ] Merge OAS vendor extensions support pages

Open
#13,765 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Is your feature request related to a problem? Please describe.

Migrate to single list of supported OAS vendor extensions.

Today, it seems like there are two different lists, where neither is a superset of the other.

Wiki: https://github.com/OpenAPITools/openapi-generator/wiki/Vendor-Extensions

This page includes x-generate-alias-as-model which is supported by all generators but not included in the following repo page.

Repo: https://github.com/OpenAPITools/openapi-generator/blob/master/docs/templating.md#extensions

This page includes x-enum-varnames and x-enum-descriptions which are supported by all generators but not listed in the wiki page.

Describe the solution you'd like

Single location which describes supported vendor extensions. It seems like it would be preferable to maintain this in a version controlled page. It would also be nice if this was a stand-alone page for vendor extensions, vs. being embedded in a larger templating page.

The page not chosen as the single location could be updated with a deprecation message and link to updated single list.

Describe alternatives you've considered

None.

Additional context

For reference, Redocly documents their OAS vendor extensions as follows:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the vendor-extension lists in the Wiki page and docs/templating.md#extensions, including the referenced Redocly examples. Choose the version-controlled location for a standalone combined list, then update the other page with a deprecation notice and link. Done means the supported extensions are documented in one location without losing any entries.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.