{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"introduction-to-openapi","__idx":0},"children":["Introduction to OpenAPI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/multi-file-definitions"},"children":["multi-file format"]}," for OpenAPI definitions."," ","OpenAPI allows for either a JSON or YAML format."," ","We recommend using the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-decisions"},"children":["YAML format"]},", and use it in our examples."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/yaml"},"children":["YAML essentials"]}," before learning OpenAPI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then, continue on to see the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/openapi-visual-reference"},"children":["OpenAPI visual reference"]}," which explores the entire specification showing snippets of the spec, samples, visual renders, and the corresponding types used in Redocly CLI."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"root-document-aka-entrypoint","__idx":1},"children":["Root document (aka entrypoint)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The entrypoint, typically named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," has the entire skeleton of the OpenAPI definition. It is known as the root document."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It has certain required properties:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["openapi"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["info"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["paths"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["And some optional properties:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["externalDocs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["servers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["components"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["tags"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["security"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a sample truncated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"openapi: 3.1.0\ninfo:\n  version: 1.0.0\n  title: Example.com\n  termsOfService: 'https://example.com/terms/'\n  contact:\n    email: contact@example.com\n    url: 'http://example.com/contact'\n  license:\n    name: Apache 2.0\n    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'\n  x-logo:\n    url: 'https://apis.guru/openapi-template/logo.png'\n  description: >\n    # Your description here\nexternalDocs:\n  description: Find out how to create a GitHub repo for your OpenAPI definition.\n  url: 'https://github.com/Rebilly/generator-openapi-repo'\ntags:\n  - name: Echo\n    description: Example echo operations\n  - name: User\n    description: Operations about user\nservers:\n  - url: 'http://example.com/api/v1'\n  - url: 'https://example.com/api/v1'\npaths:\n    # paths here\ncomponents:\n  securitySchemes:\n    # security schemes here\nsecurity:\n  - SecretAPIKey: []\n  - JWT: []\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Almost all of the complexity and effort will go into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," descriptions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend keeping the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," within the root document at a minimum, and only defining the security schemes used."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend describing the paths and schema into other files.  The paths will reference the schema ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/ref-guide"},"children":["using $refs"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"paths","__idx":2},"children":["Paths"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," in the root document should point to separate path files."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n  '/users/{username}':\n    $ref: 'paths/users@{username}.yaml'\n  /echo:\n    $ref: paths/echo.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep in mind, the path parameter must use the same name used within the curly braces within the subsequent path definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We add using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@"]}," to represent a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]}," within a filename. On the otherhand, you may wish to make a sub-folder. We discuss the pros and cons of this approach within the paths' ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["README.md"]}," file. For our examples, we'll use this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@"]}," approach and keep all of our files in the root-level of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," folder."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"path-file-example","__idx":3},"children":["Path file example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our root document references this (and other) path files. The file is named like the endpoint."," ","It contains a paths object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At the top-level of the paths object:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parameters (applies to all http methods if defined here)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["servers (if you wish to override the servers defined in the root document)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["summary"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["get"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["put"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["post"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["delete"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["options"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["head"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["patch"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["trace"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The get, put, post, delete, options, head, patch and trace refer to the http method used, and they are properties that all accept the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject"},"children":["Operation Object"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"parameters:\n  - name: pretty_print\n    in: query\n    description: Pretty print response\n    schema:\n      type: boolean\nget:\n  tags:\n    - User\n  summary: Get user by user name\n  description: |\n    Some description of the operation.\n    You can use `markdown` here.\n  operationId: getUserByName\n  parameters:\n    - name: username\n      in: path\n      description: The name that needs to be fetched\n      required: true\n      schema:\n        type: string\n    - name: with_email\n      in: query\n      description: Filter users without email\n      schema:\n        type: boolean\n  security:\n    - main_auth:\n        - 'read:users'\n    - api_key: []\n  responses:\n    '200':\n      description: Success\n      content:\n        application/json:\n          schema:\n            $ref: ../components/schemas/User.yaml\n          example:\n            username: user1\n            email: user@example.com\n    '403':\n      description: Forbidden\n    '404':\n      description: User not found\nput:\n  tags:\n    - User\n  summary: Updated user\n  description: This can only be done by the logged in user.\n  operationId: updateUser\n  parameters:\n    - name: username\n      in: path\n      description: The name that needs to be updated\n      required: true\n      schema:\n        type: string\n  security:\n    - main_auth:\n        - 'write:users'\n  responses:\n    '200':\n      description: OK\n    '400':\n      description: Invalid user supplied\n    '404':\n      description: User not found\n  requestBody:\n    content:\n      application/json:\n        schema:\n          $ref: ../components/schemas/User.yaml\n      application/xml:\n        schema:\n          $ref: ../components/schemas/User.yaml\n    description: Updated user object\n    required: true\n\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This demonstrates that the bulk of the paths file is related to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject"},"children":["Operation Object"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"operation-object","__idx":4},"children":["Operation object"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["tags"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["summary"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["externalDocs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["operationId"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["requestBody"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["responses"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["callbacks"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["deprecated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["security"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["servers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The parameters, requestBody, and response content schema can ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/ref-guide"},"children":["use $refs"]},". Using $refs will allow us to create reusable parameters and schema objects. We may also create reusable headers objects too. We find those to be the most profitable objects for re-use:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["headers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We will be adding guides to writing schema soon."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exercises-for-learning","__idx":5},"children":["Exercises for learning"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md"},"children":["OpenAPI Specification"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read examples of OpenAPI definitions. (Many companies publish their OpenAPI definitions.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Write schema to describe APIs by looking at only a request/response or docs (but not the OpenAPI definitions)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read our ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/blog/accelerated-learning-openapi"},"children":["Accelerated Learning of OpenAPI"]}," guide."]}]}]},"frontmatter":{},"tagList":[],"title":"Introduction to OpenAPI","lastModified":"2025-05-28T16:01:32.000Z"}