[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
- Run the above command.
- 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
:
- 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. - 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