Can I add examples of file contents in OpenAPI specifications?

user_694001 0
Viewed 368

My service provides upload of XML-files. The OpenApi specification does not specify a schema. I want to provide an example input. I try this:

/foo:
    post:      
      requestBody:
        content: 
          application/xml:
            schema:
              type: string
              format: binary
              example:
                  externalValue: 'https://www.w3schools.com/xml/note.xml'

However, swagger-ui produces the unhelpful:

<!-- XML example cannot be generated; root element name is undefined -->

Is it possible to specify an example from an external file?

swagger-ui openapi xml
1 Answers

This depends on what version of OpenAPI you're using.

OpenAPI 3.1

externalValue can be any valid URI. This includes relative references. See the 3.1 documentation.

OpenAPI 3.0

externalValue must be a valid URL. It cannot be a relative file path. See the 3.0 documentation.

Change your value to the hosted location of your xml file.

The swagger-ui error is telling you you're not using a named element. Try providing a name. (Note that that tool has bugs and does not correctly support all valid OpenAPI designs. For example, this related bug.)

examples:
  exampleName:
    summary: A sample object
    externalValue: 'https://www.w3schools.com/xml/note.xml'
user_54248330
Related