Response schema not properly linked

[pansen]

Description When having a OpenAPI 3.0 schema with a response schema, the response schema is not properly linked.

• [x] - I have checked that my input document is valid OpenAPI 2.0/3.0.x spec

To Reproduce Assuming this OpenAPI definition

components:
  parameters: {}
  schemas:
    FooBodySchema:
      items:
        properties:
          a_field:
            maxLength: 512
            minLength: 1
            type: string
          b_field:
            maxLength: 512
            minLength: 1
            type: string
        required:
        - a_field
        - b_field
        type: object
      type: array

info:
  title: Some API
  version: 1.0.0

openapi: 3.0.0

paths:
  /users:
    post:
      description: 'Imagine all the users living for today ...'
      operationId: users create
      parameters:
      - description: Foo bar
        in: body
        name: body
        required: true
        schema:
          $ref: '#/components/schemas/FooBodySchema'
      responses:
        200:
          description: response for 200 code
          schema:
            $ref: '#/components/schemas/FooBodySchema'
      security:
      - APIKeyHeader: []
      summary: Register user
      tags:
      - Legacy API
    x-extension: value

tags: []

We will get this Markdown part rendered

*Register user*

Imagine all the users living for today ...

<h3 id="users-create-parameters">Parameters</h3>

|Parameter|In|Type|Required|Description|
|---|---|---|---|---|
|body|body|[FooBodySchema](#schemafoobodyschema)|true|Foo bar|

<h3 id="users-create-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|response for 200 code|None|

Expected behavior I would love to see the proper schema linked like so:

*Register user*

Imagine all the users living for today ...

<h3 id="users-create-parameters">Parameters</h3>

|Parameter|In|Type|Required|Description|
|---|---|---|---|---|
|body|body|[FooBodySchema](#schemafoobodyschema)|true|Foo bar|

<h3 id="users-create-responses">Responses</h3>

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|response for 200 code|[FooBodySchema](#schemafoobodyschema)|

Screenshots Same thing further processed to Slate, will cause this HTML (bottom right is the missing schema)

Versions:

• Node.js: 10.6.0 and 8.0 are similar in results
• widdershins: 3.6.4

Additional context My commandline is

node_modules/.bin/widdershins \
				--headings 4 \
				--resolve true \
				--search false \
				--language_tabs \
					'shell:Bash' \
					'javascript:JavaScript' \
					'python:Python' \
					'ruby:Ruby' \
					'java:Java' \
				--outfile var/index.html.md \
				--verbose \
				--expandBody true \
				var/openapi_direct.yaml

Any help is appreciated. If I'm doing wrong, please tell me. If this is a bug, maybe you can give some pointers, so I can try to create a PR.

Thanks! :)

[MikeRalphson]

Your OAS document doesn't look completely valid for v3. response objects should have a content map containing media-type keys. On my phone at the moment but I can expand a bit tomorrow.

[pansen]

Awww. Thank you @MikeRalphson!

After changing to

paths:
  /users:
    post:
      description: 'Imagine all the users living for today ...'
      operationId: users create
      parameters:
      - description: Foo bar
        in: body
        name: body
        required: true
        schema:
          $ref: '#/components/schemas/FooBodySchema'
      responses:
        200:
          description: response for 200 code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FooBodySchema'
      security:
      - APIKeyHeader: []
      summary: Register user
      tags:
      - Legacy API
    x-extension: value

reference

things are working smoothly. :)

[pansen]

One question though. The spec says, I can describe different content types in this way:

      responses:
        200:
          description: response for 200 code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FooBodySchema'
            text/plain:
              schema:
                type: string

Looks like this scenario is merged to the last one, resulting in that Markdown snippet:

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|response for 200 code|string|

I guess this is a limitation of widdershins?

[mryellow]

@pansen The whole section dealing with schema parsing within responses seems to suffer from a multitude of bugs and definitely needs a re-write to support multiple response types.

https://github.com/Mermade/widdershins/issues/436

https://github.com/Mermade/widdershins/issues/437

[MikeRalphson]

@mryellow PRs welcome.

[mryellow]

Yeah it's likely I'll be getting onto this one.

Will finish working up the JSON part of my setup then move onto the markdown/html.

[MikeRalphson]

Thank you, much appreciated!