MIME types / example externalValues not respected

[LukeL99]

I'm having an issue where all of my responses are marked up as JSON, no matter what the MIME type that I use is set as. For example, this:

      responses:
        '200':
          description: 'CSV Data.'
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/CsvData'

    CsvData:
      description: Data lines in CSV format
      example: '1,2,3,4,5,'

Outputs markup with a JSON header:

```json
"1,2,3,4,5,"

I think proper behavior would be to add code highlighting hints if it's JSON or XML (or any other common interchange formats that have highlighting), but to leave the highlighting hint off if it is unknown.

[MikeRalphson]

The issue is that a schema in components/schemas doesn't itself have a media-type (it could be referenced from multiple requestBodies or responses each with multiple media-types).

The schema section is designed to give a representation of the JSON schema, hence json being used for syntax highlighting. In your example above, you actually have no schema beyond the description and example.

I'm not totally sure of the best way to accommodate this. Possibly we could take the rendered example and see if it parses as JSON, and use that to set the syntax-highlighting language?

The OAS proposal for alternateSchemas (OAI/OpenAPI-Specification#1532) might help / require a solution here.

[LukeL99]

Ah, that makes perfect sense. I am pretty new to OpenAPI, so I misunderstood some things about schemas. After reading up I get it.

I changed to an example being loaded from an external CSV file, but I'm getting 1 more issue. After generating, it's putting in weird characters that I'm not expecting.

      responses:
        '200':
          description: 'CSV Data.'
          content:
            text/csv:
              schema:
                type: string
                example:
                  $ref: './examples/csvdata.csv'

generates:

>-
  1,2,3,4,

Any idea why it's inserting:

• >-
• 2 spaces before each line
• an extra newline at the end

After resolving this I think we'll be in good shape!

[LukeL99]

This was still using a fork that I was hacking on (npm module didn't update), so this is my bug, not yours. I'll put in a PR once I get it all sorted, with CSV and plaintext support.

[LukeL99]

So, I'm kind of stuck at this point. I added some logic for handling externalValues in my fork of Widdershins and swagger2openapi, but there's something that I'm stuck on in the way the template is handling my changes.

See here for swagger2openapi:
https:/Mermade/swagger2openapi/compare/master...LukeL99:feature/lukel99/externalValues?expand=1

And here for Widdershins:
master...LukeL99:master

My changed YAML is:

responses:
        '200':
          description: 'CSV Data'
          content:
            text/csv:
              examples:
                csv:
                  externalValue: 'examples/csvdata.csv'

The problem I'm running into is:

TypeError: Cannot read property '$ref' of undefined
    at walkSchema (/Users/lukelibraro/WebstormProjects/widdershins/node_modules/swagger2openapi/walkSchema.js:13:23)
    at Object.schemaToArray (/Users/lukelibraro/WebstormProjects/widdershins/common.js:204:5)
    at Object.eval [as operation] (eval at doT.template (/Users/lukelibraro/WebstormProjects/widdershins/node_modules/dot/doT.js:133:11), <anonymous>:3:4200)
    at Object.eval [as main] (eval at doT.template (/Users/lukelibraro/WebstormProjects/widdershins/node_modules/dot/doT.js:133:11), <anonymous>:3:3497)
    at convertInner (/Users/lukelibraro/WebstormProjects/widdershins/openapi3.js:616:30)
    at /Users/lukelibraro/WebstormProjects/widdershins/openapi3.js:635:13
    at /Users/lukelibraro/WebstormProjects/widdershins/node_modules/call-me-maybe/index.js:11:28
    at process._tickCallback (internal/process/next_tick.js:176:11)

We should probably abandon this issue at this point and move the into a feature request. Hopefully you can take a look at this and see what's going on. I'm happy to clean this up and get it ready for a pull request (remove IntelliJ generated files, etc.) if you think it's a good approach.

[MikeRalphson]

We should probably abandon this issue at this point and move the into a feature request.

swagger2openapi is being rearranged into a monorepo, and is waiting on Lerna v3.0.0 being released, then we can look at raising the two PRs based on your changes. Please bear with.

[MikeRalphson]

@LukeL99 The mono-repo reorganisation has been completed now, so if you're still interested in raising a PR to (optionally) support pulling in example.externalValues that would be great. I believe I've also fixed the TypeError: Cannot read property '$ref' of undefinedproblem in the schema walker.

As this issue has touched on various things over its life, I'm going to close it as you suggested, and feel free to raise a new feature-request and/or PRs. Thanks in advance.