Example.externalValue is not displayed

[shockey]

Example Swagger/OpenAPI definition

openapi: 3.0.0

paths:
  /:
    post:
      requestBody:
        content:
          image/png:
            schema:
              type: string
              format: binary
            examples:
              KittenImage:
                externalValue: "https://placekitten.com/200/300"
      responses:
        "200":
          description: OK!

Current behavior

Expected behavior

I should be able to use the externally-referenced image as an example value for my endpoint (provided that Swagger UI is able to reach the resource).

Additional context or thoughts

#5427.

[offboarded-x233534]

I don't know if this is the appropriate issue, but instead of binary image, I simply want external JSON to display. Is this already planned?

openapi: 3.0.2
info:
  description: 'myapp'
  version: '2.0.0'
  title: 'myapp 2.0 Rest API'
servers:
  - url: http://localhost:8080/rest
    description: Local Environment
  - url: https://app-dev.myapp.foo/rest
    description: Development Environment
paths:
  /rest/companies:
    get:
      summary: 'Get all companies'
      description: 'foo'
      produces:
        - 'application/json'
      responses:
        '200':
          description: 'successful operation'
          content:
            application/json:
              schema:
                type: 'array'
                items:
                  $ref: '#/components/schemas/Company'
              examples:
                jsonObject:
                  summary: This is an example in Company
                  externalValue: 'https://static.myapp.foo/examples/rest_companies_example.json
components:
  schemas:
    Company:
      type: 'object'
      properties:
        id:
          type: 'integer'
          format: 'int64'
        name:
          type: 'string'

I build my self a quick hack, that works for me for now

47b992f...clouless:feature/examplesExternalValue

[membersound]

Same for me, would like to embed external json, but it's simply empty...

[matrunchyk]

@shockey Thank you for opening this issue! Do you know an approx. ETA for this?

[simundev]

I have the same problem. I prefer to keep my examples in external .json files (same with models) so as not to clutter the spec itself too much. Any idea where this is in the priority stack please?

[yoanncouillec]

Same here. externalValue does not display the pointed json

[verilog15]

Same here. externalValue does not work for me. It displays an empty field. Was there a 3.0.x OpenAPI version which it worked? Or is there some other way to do it without setting it manually?

[teffi]

Echoing this issue. Would be helpful to finally have externalValue work with example.

[lyzkov]

The documentation says that there is possible to use externalValue. Please update the documentation or fix a bug.

[verilog15]

Has someone found a way to bypass this issue and somehow use externalValue?

[ipichris]

Anything that can be done to get this on the roadmap?

[vaimodi]

Any workaround for this issue? Please share the details when we should expect the fix.

[ambition-consulting]

Can we get this fixed please? You have done a great job on introducing multiple example values for the multiple ways that an API endpoint can be called - now please let us also use them in your UI!

[lyzkov]

Can we get this fixed please? You have done a great job on introducing multiple example values for the multiple ways that an API endpoint can be called - now please let us also use them in your UI!

Hallo, swagger team @fehguy could you prioritise this task? External examples are crucial, I mean SUPER IMPORTANT, for spreading Single Source of Truth principle on mocking objects reusable across testing frameworks, and especially, for staging environments across platforms.

[mathis-m]

@tim-lai I think this is only partially a swagger-ui issue!
I have tried to integrate externalValue examples (from params, requestBody, response) into the sample generation process.
I realized that this value is not resolved, I think swagger-js should resolve this just like it resolves refs.

Else ways I will implement some resolver that will fetch the raw value hosted behind the externalValue url.

[veblogic]

@mathis-m , I am facing the same issue. Is this issue resolved?
Appreciate your efforts and time invested.

[arman-sydikov]

Workaround with wrapComponents

Sample openapi.yaml

openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server'
  version: 1.0.0
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
paths:
  /router/rest:
    get:
      summary: test
      operationId: test
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
              examples:
                success:
                  summary: JSON example
                  value: Loading...
                  externalValue: 'example/test.json'
            application/xml:
              schema:
                type: object
                xml:
                  name: xml
              examples:
                success:
                  summary: XML example
                  value: Loading...
                  externalValue: 'example/test.xml'

Add custom plugin to index.html

// Examples map
const examples = {};

// Custom plugin for logic that happens before the response element is created
const CustomPlugin = () => {
  return {
    wrapComponents: {
      response: (Original, { React, oas3Actions, oas3Selectors }) => (props) => {
        const contentType = oas3Selectors.responseContentType(props.path, props.method)
        const externalValue = props.response.getIn(['content', contentType, 'examples', props.activeExamplesKey, 'externalValue'])
        // Check if externalValue field exists
        if (externalValue) {
          // Check if examples map already contains externalValue key
          if (examples[externalValue]) {
            // Set example value directly from examples map
            props.response = props.response.setIn(['content', contentType, 'examples', props.activeExamplesKey, 'value'], examples[externalValue])
          } else {
            // Download external file
            fetch(externalValue)
            .then(res => res.text())
            .then(data => {
              // Put downloaded file content into the examples map
              examples[externalValue] = data
              // Simulate select another example action
              oas3Actions.setActiveExamplesMember({
                "name": 'fake',
                "pathMethod": [props.path, props.method],
                "contextType": "responses",
                "contextName": props.code
              })
              // Reselect this example
              oas3Actions.setActiveExamplesMember({
                "name": props.activeExamplesKey,
                "pathMethod": [props.path, props.method],
                "contextType": "responses",
                "contextName": props.code
              })
            })
            .catch(e => console.error(e))
          }
        }
        return React.createElement(Original, props)
      }
    }
  }
}

window.onload = function() {
  const ui = SwaggerUIBundle({
    url: 'openapi.yaml',
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl,
      // Add custom plugin
      CustomPlugin
    ],
    layout: "StandaloneLayout"
  });

  window.ui = ui;
};

[sjaakd]

I guess this issue also applies to having xml documents as example#externalValue. I'm dealing with the annotation version of openapi (org.eclipse.microprofile.openapi.annotations) and having problems with large String constants as example#value. Falling back on example#externalValue does not work.

[ShambuGIT]

I am facing the same issue. The workaround helps to make it work. But can anyone provide me the permanent fix on this.

[sima0815]

Thanks for this fix! Do you have any suggestions on how to get this working for the request body as well. I want to have an example with an external JSON File within the Request Body.

Workaround with wrapComponents

Sample openapi.yaml

openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server'
  version: 1.0.0
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
paths:
  /router/rest:
    get:
      summary: test
      operationId: test
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
              examples:
                success:
                  summary: JSON example
                  value: Loading...
                  externalValue: 'example/test.json'
            application/xml:
              schema:
                type: object
                xml:
                  name: xml
              examples:
                success:
                  summary: XML example
                  value: Loading...
                  externalValue: 'example/test.xml'

Add custom plugin to index.html

// Examples map
const examples = {};

// Custom plugin for logic that happens before the response element is created
const CustomPlugin = () => {
  return {
    wrapComponents: {
      response: (Original, { React, oas3Actions, oas3Selectors }) => (props) => {
        const contentType = oas3Selectors.responseContentType(props.path, props.method)
        const externalValue = props.response.getIn(['content', contentType, 'examples', props.activeExamplesKey, 'externalValue'])
        // Check if externalValue field exists
        if (externalValue) {
          // Check if examples map already contains externalValue key
          if (examples[externalValue]) {
            // Set example value directly from examples map
            props.response = props.response.setIn(['content', contentType, 'examples', props.activeExamplesKey, 'value'], examples[externalValue])
          } else {
            // Download external file
            fetch(externalValue)
            .then(res => res.text())
            .then(data => {
              // Put downloaded file content into the examples map
              examples[externalValue] = data
              // Simulate select another example action
              oas3Actions.setActiveExamplesMember({
                "name": 'fake',
                "pathMethod": [props.path, props.method],
                "contextType": "responses",
                "contextName": props.code
              })
              // Reselect this example
              oas3Actions.setActiveExamplesMember({
                "name": props.activeExamplesKey,
                "pathMethod": [props.path, props.method],
                "contextType": "responses",
                "contextName": props.code
              })
            })
            .catch(e => console.error(e))
          }
        }
        return React.createElement(Original, props)
      }
    }
  }
}

window.onload = function() {
  const ui = SwaggerUIBundle({
    url: 'openapi.yaml',
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl,
      // Add custom plugin
      CustomPlugin
    ],
    layout: "StandaloneLayout"
  });

  window.ui = ui;
};

[CxVercility]

Push.
How has this not been fixed in 2 and a half years?!

[mathis-m]

Push.
How has this not been fixed in 2 and a half years?!

If you have time have a look at swagger-api/swagger-js#1978 and finish it up. Currently I have no time to work on it.

[Aravinda93]

Hello Team,

I am working on Open-API and facing the same issue. Can you please provide me with some workaround?
I have posted my question here: https://stackoverflow.com/q/71779533/7584240

@mathis-m @arman-sydikov If you get a chance please provide some work-around. Thanks a lot in advance.

[natemow]

In case it helps somebody else...I'm using swagger-ui-dist and replacing stuff in the package using good ol' Bash. I switched from swagger.json to swagger.yaml for doc output so multiline strings could be stored in example.MyKey.value. Here's a Bash workaround for populating example.MyKey.value in the generated swagger.yaml...it's just replacing value: path with that file's contents:

# Read in example and insert 8 spaces at the beginning of each line (for proper YAML formatting).
EXAMPLE='/path/to/examples/example.xml';
VALUE=$(cat "$EXAMPLE");
VALUE=$(echo "$VALUE" | sed 's/^/        /');

# Use awk var substitution to insert multiline value.
awk -v search="value: $EXAMPLE" -v replace="value: |-\n$VALUE" "{gsub(search,replace)}1" ./swagger.yaml > ./temp.yaml \
  && mv ./temp.yaml swagger.yaml;

[CxVercility]

Push.
How has this not been fixed in 2 and a half years?!

If you have time have a look at swagger-api/swagger-js#1978 and finish it up. Currently I have no time to work on it.

I dont have any experience with JS and that's not the point i was trying to convey to be honest.
Im not asking you to make it work in your free time, but the least that should be done is a deprecation of that option with a fat warning or a flat out removal so people dont waste their time trying to get this to work, if you don't intend to do anything about it any time soon

[mathis-m]

@tim-lai @char0n This is a really low hanging fruit. Can you please give this some priority on "your internal backlog"

In addition, this is not a swagger-ui issue. It arises because of wrong resolution / normalization in the swagger-js package.

[mathis-m]

It is literally all there, in my initial pr at swagger-api/swagger-js#2013

It is just missing the base64 part and some tests.

[ben12]

Any news ?

[char0n]

Hi @ben12,

This is actually already supported in SwaggerUI@5 and OpenAPI 3.1.0 definitions.

openapi: 3.1.0
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server'
  version: 1.0.0
servers:
  - url: https://petstore.swagger.io/v2
  - url: http://petstore.swagger.io/v2
paths:
  /router/rest:
    get:
      summary: test
      operationId: test
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                type: object
              examples:
                success:
                  summary: JSON example
                  externalValue: https://gist.githubusercontent.com/char0n/5c35aee4fd95a23b18f6ed76d51ce83f/raw/0014ab1e8882ffbe285465ded4c18b4b745aecc4/test.yaml

URIs with .yaml, .yml, and .json extensions are currently natively supported. In all other cases the content of the externalValue is fetched, base64 encoded and assign to value field. Now I'm only explaining how it works so far, if anybody have any suggestions how to make it better, we're more then open to it.

---

Related to OpenAPI 3.0.x support, work for this has been done already by @mathis-m in swagger-api/swagger-js#2013, but in long term we want OpenAPI 3.0.x resolution to be facilitated by ApiDOM (same as for OpenAPI 3.1.0) and not by old legacy specmap mechanism.

[ben12]

Thanks, it work. My mistake was the OpenApi version (3.0.3 instead of 3.1.0).

So this issue may be closed ?

[char0n]

Thanks, it work. My mistake was the OpenApi version (3.0.3 instead of 3.1.0).

I'm just glad that you can use this feature for your OpenAPI 3.1.0 definitions now.

So this issue may be closed ?

Not really, as we're still missing this feature for OpenAPI 3.0.x. We'll introduce ApiDOM facilitated resolution for OpenAPI 3.0.x as an opt-in behavior in SwaggerClient and SwaggerUI subsequently. If/When we have this, we can close this issue.

[markliuliu]

Hi @char0n, Thanks for your comment, By your comment we are able to use OpenAPI 31 to show the external Value. But we still have some questions.
Is any reason Swagger UI have to use Base64 to encode the format not list above like csv?
Is there any way let Swagger UI don't encode our value or help us to decode in value block?

env:
OpenAPI 3.1.0
Swagger UI 5.0.0