Swagger UI - Issue with external JSON schema files

Question

I design API with Swagger and use Swagger UI to display them on our corporate API Design Website. I have a JSON file who contains a JSONSCHEMA with every variables I would like to use in multiples SWAGGER files.

For example, given the foo.json file containing the following schema :

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "fooooo",
    "version": "2021_11",
    "type": "object",
    "definitions": {
        "EligibilityNotification": {
            "type":"object",
            "properties": {
                "code": {
                    "type": "string"
                },
                "label": {
                    "type": "string"
                }
            }
        }
    }
}

I have the following swagger file :

components:
   NotificationGroup:
      type: object
      properties:
        eligibilityNotifications:
          type: array
          items:
            $ref: '../JSONSchemas/foo.json#/definitions/EligibilityNotification'

The relative path is correct I double checked it before creating the topic.

I have the following issue localy when I browse the swagger throught the "OpenAPI SwaggerUI preview" Visual Studio Code's pluggin :

"Unknown Type: object,null"

user_8607180 · Answer

It does not seem like the components definition is correct: for OpenAPI 3.0 spec, it should include schemas section; for OpenAPI 2.0 it should be named definitions.

You might also want to install OpenAPI (Swagger) Editor extension to validate the spec.

Here is a working example for OpenAPI 3.0:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts

paths:
  /notifications:
    post:
      description: Returns notifications
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  notifications:
                    $ref: "#/components/schemas/NotificationGroup"

components:
  schemas:
    NotificationGroup:
      type: object
      properties:
        eligibilityNotifications:
          type: array
          items:
            $ref: "../JSONSchemas/foo.json#/definitions/EligibilityNotification"

It renders as following (I used Swagger Viewer for rendering):

And just in case if you want to go with OpenAPI 2.0, here is another working example for the swagger: "2.0" spec:

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https

paths:
  /notifications:
    post:
      summary: Returns notifications
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            properties:
              notifications:
                $ref: "#/definitions/NotificationGroup"

definitions:
  NotificationGroup:
    properties:
      eligibilityNotifications:
        type: array
        items:
          $ref: "../JSONSchemas/foo.json#/definitions/EligibilityNotification"

Swagger UI - Issue with external JSON schema files

1 Answers