[BUG] x-enum-varnames is underspecified

Created by: kevinoid

Description

Support for the x-enum-varnames extension was added in #917 to support specifying variable names for enumeration values (e.g. for numeric values, as in https://github.com/OpenAPITools/openapi-generator/issues/893#issuecomment-416617460). The documentation from #2010 suggests that the names will undergo language-specific normalization (as enum values would), but they do not, which can result in broken code.

openapi-generator version

The issue has been present since #917 was merged. Tested on master.

OpenAPI declaration file content or url

openapi: '3.0.2'
info:
  title: x-enum-varnames example
  version: '1.0.0'
components:
  schemas:
    WeatherType:
      type: integer
      enum:
      - 0
      - 1
      - 2
      x-enum-varnames:
      - Sunny
      - Partly Cloudy
      - Rainy
paths:
  /weather:
    get:
      responses:
        default:
          description: Current weather
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherType'

Command line used for generation

openapi-generator-cli.jar generate -i openapi.yaml -g java -o bad-x-enum-varnames-java

Steps to reproduce

1. Run the above command.
2. Try to compile the generated code, which will fail due to Partly Cloudy being an invalid variable name.

Suggest a fix

The appropriate fix depends on the desired semantics of x-enum-varnames:

1. If x-enum-varnames should be a natural language name, then the values should be converted to identifiers in the same way as enum values (as suggested in the documentation), which would fix the above example.
2. If x-enum-varnames must be a valid identifier (in every language which can be generated) then the documentation should be updated to clarify that. (Ideally the code generation would also fail more gracefully.)

A problem with the first option is that it prevents an existing use case of overriding the generator convention, as described in https://github.com/swagger-api/swagger-codegen/issues/7466#issuecomment-483602884, and could change the generated API by changing the generated names (depending on how identifier normalization is done).

A problem with the second option is that different languages have different casing conventions for enumeration values and there's no way to satisfy them all. Should the spec use PARTLY_CLOUDY, PartlyCloudy, or partlyCloudy for x-enum-varnames? Any choice will be unconventional in several languages. Also, different languages have different rules for valid identifiers and requiring spec authors to comply with all of them is burdensome.

Thanks for considering, Kevin