Swagger 3.0 example (OpenApi 3.0 sample example)

Swagger 3.0 example (OpenApi 3.0 sample example)

Swagger 30 example OpenApi 31 example Swagger 30 example OpenApi 30 sample example

Today In this article, we will see a Swagger 3.0 example with a JSON sample. We shall see a basic sample, samples with authorization headers like JWT bearer or Basic Authentication headers, etc.

Today in this article, we will cover below aspects,

With the open API Specifications, there are a few improvements done to the JSON schema

OpenApi 3.0 json example

Below is a sample Open API JSON for JWT Authentication Header with Global scope,

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz-Service",
    "version": "v1"
  },
  "paths": {
    "/api/Pay": {
      "get": {
        "tags": [
          "Pay"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Employee": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          },
          "name": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "JWT Authorization header using the Bearer scheme.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Swagger JSON for openapi 30 for jwt bearer authenticaiton Swagger 30 example OpenApi 30 sample example

Below is a sample Open API JSON for JWT Authentication Header with Global scope,

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz-Service",
    "version": "v1"
  },
  "paths": {
    "/api/Pay": {
      "get": {
        "tags": [
          "Pay"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/Employee"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Employee": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          },
          "name": {
            "type": "string",
            "nullable": true,
            "readOnly": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "JWT Authorization header using the Bearer scheme.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

OpenApi 3.0 sample JSON example for Basic Authentication Header

Below is a sample Open API JSON for Basic Authentication Header with Global scope,

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz-Service",
    "version": "v1"
  },
  "paths": {
    "/Accounts": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WeatherForecast": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "temperatureC": {
            "type": "integer",
            "format": "int32"
          },
          "temperatureF": {
            "type": "integer",
            "format": "int32",
            "readOnly": true
          },
          "summary": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "description": "Basic Authorization header.",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ]
}
Swagger JSON for openapi 30 for basic authenticaiton Swagger 30 example OpenApi 30 sample example

Below is a sample Open API JSON for Basic Authentication Header with Local scope

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz-Service",
    "version": "v1"
  },
  "paths": {
    "/Accounts": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "security": [
          {
            "basic": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "WeatherForecast": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "temperatureC": {
            "type": "integer",
            "format": "int32"
          },
          "temperatureF": {
            "type": "integer",
            "format": "int32",
            "readOnly": true
          },
          "summary": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "description": "Basic Authorization header.",
        "scheme": "basic"
      }
    }
  }
}

References:

Do you have any comments or ideas or any better suggestions to share?

Please sound off your comments below.

Happy Coding !!



Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.



Leave a Comment

Your email address will not be published. Required fields are marked *