Vendor extension references not resolved

[arr28]

Description

When parsing a swagger file during codegen, almost all references are resolved - i.e. when producing the input file for a mustache template, the referenced YAML is inserted into the referring object.

However, this isn't happening for vendor extensions, meaning that I can't generate the docs & stubs that I need.

Swagger-codegen version

Master (as of 2017-01-09 ~09:30 UTC, i.e. 81b5b78).

Swagger declaration file content or url

At the top level of the YAML spec, there are some vendor extensions. (In this case, they define common error information, used in several places throughout the rest of the API.)

x-error-defs:
  credentialTooShort:
    errorID: credentialTooShort
    message: Credential %1 is shorter than the minimum allowed (%2).
    variables:
      - The credential field which is too short.
      - The minimum permitted credential length.
  credentialTooLong:
    errorID: credentialTooLong
    message: Credential %1 is longer than the maximum allowed (%2).
    variables:
      - The credential field which is too long.
      - The maximum permitted credential length.

Within a particular response to an operation, there is a vendor extension with references to the top-level extensions. (In this case, error response objects refer to particular errors that might be returned from the operation.)

        '400':
          description: |
            The account could not be created because a credential didn't meet the complexity requirements.
          schema:
            $ref: './shared/error.yaml#/error'
          x-error-refs:
            - '$ref': '#/x-error-defs/credentialTooShort'
            - '$ref': '#/x-error-defs/credentialTooLong'

Command line used for generation

java -DdebugOperations -jar ../../../swagger-codegen/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i credentials.yaml -l html2

Steps to reproduce

Generate API docs using the command line above for a Swagger spec. containing the YAML fragments above. Reproduces 100% of the time.

Related issues

Until yesterday, vendor extensions in responses didn't work at all. This was fixed under #4022, in so far as the extensions do now appear in the mustache input file - it's just that the references aren't being resolved.

Suggest a Fix

Fully resolve references in vendor extensions, just like in other places (e.g. parameters).

[arr28]

I'd be happy to take a look at this if (a) you're happy with the approach outlined in "Suggest a Fix" and (b) somebody could give me some pointers.

[fehguy]

@arr28 sorry for the delay. Parsing will be done under the swagger-parser project. Could you please open an issue there so we can resolve this?

[ankeshanand]

@fehguy It seems swagger parses the outer level vendorExtensions correctly, since I can see them in the response of -DdebugOperations, but codegen is not able to use them.

Any pointers to how we can use them, or could you point to necessary changes that can be made in swagger-codegen source so that I can use them?

[fehguy]

Well, the extensions are resolved, as I mentioned in the parser ticket. The problem is that the parser is not responsible fore resolving JSON References where they are not explicitly enabled in the spec. So the codegen won't have access the the resolved parse.

The correct solution is a bit involved but technically:

• Create a parser extension that resolves the references that you want to handle, such as those in your ticket:

x-error-refs:
- '$ref': '#/x-error-defs/credentialTooShort'
- '$ref': '#/x-error-defs/credentialTooLong'

• Include that extension in your classpath when executing codegen
• Access the extensions in your templates

That's the theoretical right path--please ping back if that doesn't make sense.

[arr28]

Makes sense, but we'll stick with our alternative workaround. (We're producing HTML output and are able to fix up the cross-references with some javascript hackery.)