Search code examples
swagger-uiopenapiswagger-editor

Why do external docs show up before servers in Swagger UI?

I have the following OpenAPI YAML definition. The externalDocs section is underneath the servers section but it shows up before the server in the preview in the Swagger Editor (https://editor.swagger.io/). Why is that?

openapi: 3.0.0
info:
  title: Service
  description: >- 
    Service description
  version: '1.0'
  termsOfService: >-
    https://pdf/API_Developer_Agreement.pdf
  contact:
    email: 'contact@contact.com'
    name: 'contact Europa'
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
externalDocs:
  description: "externalDocs"
  url: 'https://externalDocs'

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

enter image description here

Solution

  • The display order of the info, externalDocs and servers sections in Swagger UI is predefined and does not depend on their order in the YAML/JSON file.

    However, individual servers in servers, individual paths and operations in paths, and individual properties in schemas are by default displayed in the same order as they are listed in your API definition.