externalDocs missing from tags, schemata and operations.

[m-mohr]

I have this OpenAPI 3.0 specification:

...
    "/processes": {
      "get": {
        "summary": "List supported processes.",
        "description": "The request asks the back-end for available processes and returns detailed process descriptions, including parameters and return values. Processes are described using the Functio specification for language-agnostic process descriptions.",
        "tags": [
          "Process Discovery"
        ],
        "externalDocs": {
          "description": "Functio specification, version 0.1.0 (or any newer patch version).",
          "url": "https://github.com/m-mohr/functio-spec/blob/master/versions/0.1.0/spec.md"
        },
        "responses": {
          "200": {
            "description": "Functio document describing the supported processes.",
            "content": {
              "application/json": {
                "schema": {
                  "externalDocs": {
                    "description": "Functio specification, version 0.1.0 (or any newer patch version).",
                    "url": "https://github.com/m-mohr/functio-spec/blob/master/versions/0.1.0/spec.md"
                  }
                },
                "examples": {
                  "functioSpecExample": {
                    "externalValue": "https://raw.githubusercontent.com/m-mohr/functio-spec/master/versions/0.1.0/example.json"
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/client_error_auth"
          },
          "5XX": {
            "$ref": "#/components/responses/server_error"
          }
        }
      }
    },
...

Both externalDocs are not rendered by ReDoc as you can see here:
https://open-eo.github.io/openeo-api/v/0.3.0/apireference/index.html#/paths/~1processes/get

Would be helpful to have this feature implemented.

[m-mohr]

Do you think this will be considered soon? Otherwise I'd need to start adding the externalDocs in the descriptions using markdown.

[RomanHotsiy]

Yes, it will.
PR's are welcome!

[m-mohr]

I just checked the status of External Documentation rendering in ReDoc:

• OpenAPI/Swagger Object: Works as expected
• Operation Object: Not shown, but model available
• Schema Object: Not shown, but model available
• Tag Object: Not shown, but model available

Used this OpenAPI 3.0 spec for testing:

openapi: 3.0.1
info:
  title: External Documentation Test
  version: 0.3.0
externalDocs:
  description: ExternalDocs in OpenAPI Object
  url: 'https://example.com'
tags:
  - name: Group
    externalDocs:
      description: ExternalDocs in Tag Object
      url: 'https://example.com'
paths:
  /example:
    get:
      summary: Example operation
      description: This is a simple example to show whether externalDocs is working with ReDoc or not.
      tags:
        - Group
      externalDocs:
        description: ExternalDocs in Operation Object
        url: 'https://example.com'
      responses:
        '200':
          description: This is a sample schema for a response.
          content:
            application/json:
              schema:
                type: string
                externalDocs:
                  description: ExternalDocs in Schema Object
                  url: 'https://example.com'

[m-mohr]

@RomanGotsiy I created a PR (#595) to solve this issue. Please feel free to review and add feedback as it was my first time working with React and there may be some issues.

[matthunter]

I am also interested in this feature. Is there timeline when this will get in?

[RomanHotsiy]

I will review @m-mohr's PR ASAP. Hopefully this week.

[m-mohr]

@RomanGotsiy Would be appreciated as I really had problems to solve conflicts in merges with the recent changes and won't have much time to solve them again.

[m-mohr]

Solved.