{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://www.krakend.io/schema/v3.0/documentation/openapi-endpoint.json",
  "title": "Generate endpoint documentation using OpenAPI",
  "description": "Enterprise only. Documents the endpoint so you can [automatically generate OpenAPI documentation](https://www.krakend.io/docs/enterprise/developer/openapi/) through `krakend openapi export` command.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
  "type": "object",
  "properties": {
    "description": {
      "title": "Endpoint description",
      "description": "A detailed explanation of what the endpoint does, supporting [CommonMark](https://commonmark.org/help/) syntax. Use `summary` for a short version.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        "Lists all users in the system, paginated in blocks of 50 users"
      ],
      "type": "string"
    },
    "audience": {
      "title": "Audience",
      "description": "The list of audiences that will consume this endpoint. These values **do not define the gateway logic** in any way. They are a way to group endpoints and filter them out when generating the OpenAPI documentation. Use `*` to indicate an endpoint will be present in any audience generated.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [ "gold", "silver", "*" ]
      ],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "custom_security_schemes": {
      "title": "Custom security schemes",
      "description": "The custom security schemes that apply to this endpoint. Write each scheme name as declared in the service-level `custom_security_schemes`, with an empty object as value, e.g., `{\"OAuth2Security\":{}}`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        {
          "OAuth2Security": {}
        }
      ],
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "title": "Security Scheme",
          "description": "An empty object referencing a security scheme defined at the service level.",
          "type": "object",
          "maxProperties": 0
        }
      }
    },
    "disable_default_response_definitions": {
      "title": "Disable default response definitions",
      "description": "By default, KrakenD adds a `500` and a `200` response definition to the endpoint. Set this property to `true` to avoid this behavior.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "default": false,
      "type": "boolean"
    },
    "example": {
      "title": "Example",
      "description": "**Deprecated in OAS3** (use `response_definition` instead). A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the `output_encoding=string`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "type": [ "object", "string" ]
    },
    "header_definition": {
      "title": "Header definition",
      "description": "Sets a detailed description for the headers allowed in the endpoint. Make sure to include the same headers in the endpoint's `input_headers`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [
          {
            "description": "The type of content",
            "name": "Content-Type"
          }
        ]
      ],
      "type": "array",
      "items": {
        "title": "Headers definition",
        "type": "object",
        "anyOf": [
          {
            "required": [ "name" ]
          },
          {
            "required": [ "ref" ]
          }
        ],
        "properties": {
          "description": {
            "title": "Description",
            "description": "The description of the header.",
            "examples": [ "The Content-Type sets the encoding of the request" ],
            "type": "string"
          },
          "type": {
            "title": "Type",
            "description": "The type of data according to the OpenAPI spec",
            "examples": [ "string" ],
            "default": "string",
            "enum": [
              "integer",
              "string",
              "boolean",
              "object",
              "array",
              "float",
              "date-time"
            ]
          },
          "enum": {
            "title": "Enum",
            "description": "The allowed values for this header",
            "examples": [
              [ "application/json", "application/xml" ]
            ],
            "type": "array",
            "items": {
              "type": [
                "array",
                "boolean",
                "integer",
                "number",
                "object",
                "string"
              ]
            }
          },
          "required": {
            "title": "Required",
            "description": "Set to `true` when this header is required.",
            "default": false,
            "type": "boolean"
          },
          "hide": {
            "title": "Hide header",
            "description": "Hides this header from the generated documentation.",
            "default": false,
            "type": "boolean"
          },
          "name": {
            "title": "Name",
            "description": "The name of the header, as declared in `input_headers`",
            "type": "string"
          },
          "ref": {
            "title": "Reference",
            "description": "The name of a parameter declared in the service-level `components_parameters`, without the `#/components/parameters/` prefix. When you set `ref`, the `name` is not needed.",
            "examples": [ "PageParam" ],
            "type": "string"
          }
        },
        "patternProperties": {
          "^[@$_#]": true
        },
        "additionalProperties": false
      }
    },
    "operation_id": {
      "title": "Operation ID",
      "description": "A unique identifier of the operation, usually the method plus the endpoint. If provided, each ID must be unique among all operations described in your API.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [ "GET/foo" ],
      "type": "string"
    },
    "param_definition": {
      "title": "Param definition",
      "description": "Sets a detailed description for the URL parameters (e.g., `/foo/{param}`) required in the endpoint. Write each parameter name exactly as in the endpoint definition.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [
          {
            "description": "The unique user ID",
            "name": "id_user"
          }
        ]
      ],
      "type": "array",
      "items": {
        "title": "Parameters",
        "type": "object",
        "anyOf": [
          {
            "required": [ "name" ]
          },
          {
            "required": [ "ref" ]
          }
        ],
        "properties": {
          "description": {
            "title": "Description",
            "description": "The description of the parameter.",
            "type": "string"
          },
          "examples": {
            "title": "Examples",
            "description": "Multiple example values for this parameter, where each key is the name of the example.",
            "type": "object",
            "patternProperties": {
              "^.*$": {
                "type": [ "string", "number", "boolean", "array", "object" ]
              }
            }
          },
          "type": {
            "title": "Type",
            "description": "The type of data according to the OpenAPI spec",
            "examples": [ "string" ],
            "default": "string",
            "enum": [
              "integer",
              "number",
              "string",
              "boolean",
              "object",
              "array",
              "float",
              "date-time"
            ]
          },
          "enum": {
            "title": "Enum",
            "description": "The allowed values for this parameter",
            "examples": [
              [ "application/json", "application/xml" ]
            ],
            "type": "array",
            "items": {
              "type": [
                "array",
                "boolean",
                "integer",
                "number",
                "object",
                "string"
              ]
            }
          },
          "format": {
            "title": "Format",
            "description": "The extending format for the previously defined type. If the type is `number` or `string`, you can apply one of the available formats. The linter does not check that the format matches the type.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "enum": [
              "int32",
              "int64",
              "float",
              "double",
              "date",
              "date-time",
              "byte",
              "uuid",
              ""
            ]
          },
          "required": {
            "title": "Required",
            "description": "A path parameter is always mandatory on KrakenD, but you can still generate the OpenAPI documentation saying otherwise.",
            "default": true,
            "type": "boolean"
          },
          "example": {
            "title": "Example",
            "description": "An example value for this parameter. This example is injected in the spec as is.",
            "type": [ "string", "number", "boolean", "array", "object" ]
          },
          "hide": {
            "title": "Hide param",
            "description": "Hides this parameter from the generated documentation, although it is still part of the endpoint definition.",
            "default": false,
            "type": "boolean"
          },
          "name": {
            "title": "Name",
            "description": "The name of the parameter, as declared in `endpoint` without the curly braces `{}`",
            "type": "string"
          },
          "ref": {
            "title": "Reference",
            "description": "The name of a parameter declared in the service-level `components_parameters`, without the `#/components/parameters/` prefix. When you set `ref`, the `name` is not needed.",
            "examples": [ "PageParam" ],
            "type": "string"
          }
        },
        "patternProperties": {
          "^[@$_#]": true
        },
        "additionalProperties": false
      }
    },
    "query_definition": {
      "title": "Query definition",
      "description": "Sets a detailed description for the query strings allowed in the endpoint. Make sure to include the same strings in the endpoint's `input_query_strings`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [
          {
            "description": "The number of the page",
            "name": "page"
          }
        ]
      ],
      "type": "array",
      "items": {
        "title": "Query strings",
        "type": "object",
        "anyOf": [
          {
            "required": [ "name" ]
          },
          {
            "required": [ "ref" ]
          }
        ],
        "properties": {
          "description": {
            "title": "Description",
            "description": "The description of the query string.",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "description": "The type of data according to the OpenAPI spec",
            "default": "string",
            "enum": [
              "integer",
              "number",
              "string",
              "boolean",
              "object",
              "array",
              "float",
              "date-time"
            ]
          },
          "enum": {
            "title": "Enum",
            "description": "The allowed values for this query definition",
            "type": "array",
            "items": {
              "type": [
                "array",
                "boolean",
                "integer",
                "number",
                "object",
                "string"
              ]
            }
          },
          "format": {
            "title": "Format",
            "description": "The extending format for the previously defined type. If the type is `number` or `string`, you can apply one of the available formats. The linter does not check that the format matches the type.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "enum": [
              "int32",
              "int64",
              "float",
              "double",
              "date",
              "date-time",
              "byte",
              "uuid",
              ""
            ]
          },
          "required": {
            "title": "Required",
            "description": "Set to `true` when this query string is required.",
            "default": true,
            "type": "boolean"
          },
          "hide": {
            "title": "Hide query string",
            "description": "Hides this query string from the generated documentation.",
            "default": false,
            "type": "boolean"
          },
          "name": {
            "title": "Name",
            "description": "The name of the query string, as declared in `input_query_strings`.",
            "type": "string"
          },
          "example": {
            "title": "Example",
            "description": "An example value for this query string.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "type": [
              "string",
              "object",
              "array",
              "boolean",
              "integer",
              "null",
              "number"
            ]
          },
          "ref": {
            "title": "Reference",
            "description": "The name of a parameter declared in the service-level `components_parameters`, without the `#/components/parameters/` prefix. When you set `ref`, the `name` is not needed.",
            "examples": [ "PageParam" ],
            "type": "string"
          }
        },
        "patternProperties": {
          "^[@$_#]": true
        },
        "additionalProperties": false
      }
    },
    "request_definition": {
      "title": "Definition of a request",
      "description": "Describes the payload needed to consume the endpoint. If a JSON Schema validation exists, it takes precedence when generating the documentation. An example use case is when you need to document a `multipart/form-data` request body. This property is an array because you can document requests with multiple content types.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [
          {
            "description": "Updates the user",
            "content_type": "application/json",
            "example": {
              "first_name": "Mary",
              "id_user": 33
            }
          }
        ]
      ],
      "type": "array",
      "items": {
        "required": [ "content_type" ],
        "properties": {
          "description": {
            "title": "Description",
            "description": "The description of the payload this endpoint accepts.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "type": "string"
          },
          "content_type": {
            "title": "Content Type",
            "description": "The content type of the request payload, e.g., `application/json`. You cannot repeat this content type in another item.",
            "type": "string"
          },
          "example": {
            "title": "Example",
            "description": "A free form JSON object or a string you would like to show as a sample request payload of the endpoint. The examples assume they are JSON content types.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "type": [
              "string",
              "object",
              "array",
              "boolean",
              "integer",
              "null",
              "number"
            ]
          },
          "examples": {
            "title": "Examples",
            "description": "A free form JSON object or a string you would like to show as a sample request payload of the endpoint. The examples assume they are JSON content types.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
            "examples": [
              {
                "Example 1": {
                  "msg": "a message"
                }
              },
              {
                "Example 1": {
                  "msg": "a message"
                },
                "Example 2": {
                  "error": "an error message"
                }
              }
            ],
            "type": "object",
            "additionalProperties": {
              "title": "Example",
              "type": [
                "string",
                "object",
                "array",
                "boolean",
                "integer",
                "null",
                "number"
              ]
            }
          },
          "example_schema": {
            "description": "A JSON schema that describes the request format for the accepted payload in the endpoint. Use either `example` or `example_schema`, but not both.",
            "type": [ "string", "object" ]
          },
          "ref": {
            "title": "Reference",
            "description": "The relative reference to the `components/schemas` OpenAPI definition that describes the accepted request. Notice that the path `#/components/schemas/` is not needed.",
            "examples": [ "your_schema_name" ],
            "type": "string"
          }
        },
        "patternProperties": {
          "^[@$_#]": true
        },
        "additionalProperties": false
      }
    },
    "response_definition": {
      "title": "Definition of responses (OAS3 only)",
      "description": "Describes the different status codes returned by this endpoint. Each key is a status code represented as a string, e.g., `200` (success), `500` (internal error), or `default`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        {
          "404": {
            "description": "Page not found",
            "@comment": "Some comment",
            "content_type": "application/json",
            "example": {
              "status": "KO"
            }
          }
        }
      ],
      "type": "object",
      "patternProperties": {
        "default|^[0-9]+$": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "description": {
                  "title": "Description",
                  "description": "The description of this status code, e.g., `Page not found`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                  "type": "string"
                },
                "content_type": {
                  "title": "Content Type",
                  "description": "The content type returned with this status code, e.g., `application/json`.",
                  "type": "string"
                },
                "example": {
                  "title": "Example",
                  "description": "A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the `output_encoding=string`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                  "type": [
                    "string",
                    "object",
                    "array",
                    "boolean",
                    "integer",
                    "null",
                    "number"
                  ]
                },
                "examples": {
                  "title": "Examples",
                  "description": "A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the `output_encoding=string`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                  "examples": [
                    {
                      "Example 1": {
                        "msg": "a message"
                      }
                    },
                    {
                      "Example 1": {
                        "msg": "a message"
                      },
                      "Example 2": {
                        "error": "an error message"
                      }
                    }
                  ],
                  "type": "object",
                  "additionalProperties": {
                    "title": "Example",
                    "type": [
                      "string",
                      "object",
                      "array",
                      "boolean",
                      "integer",
                      "null",
                      "number"
                    ]
                  }
                },
                "example_schema": {
                  "description": "A JSON schema that describes the response format for the endpoint, directly as a JSON object, or encoded as a base64 string. Use either `example` or `example_schema`, but not both.",
                  "type": [ "string", "object" ]
                },
                "ref": {
                  "title": "Reference",
                  "description": "The relative reference to the `components/schemas` OpenAPI definition that describes this response. Notice that the path `#/components/schemas/` is not needed.",
                  "examples": [ "your_schema_name" ],
                  "type": "string"
                }
              },
              "patternProperties": {
                "^[@$_#]": true
              },
              "additionalProperties": false
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "description": {
                    "title": "Description",
                    "description": "The description of this status code, e.g., `Page not found`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                    "type": "string"
                  },
                  "content_type": {
                    "title": "Content Type",
                    "description": "The content type returned with this status code, e.g., `application/json`.",
                    "type": "string"
                  },
                  "example": {
                    "title": "Example",
                    "description": "A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the `output_encoding=string`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                    "type": [
                      "string",
                      "object",
                      "array",
                      "boolean",
                      "integer",
                      "null",
                      "number"
                    ]
                  },
                  "examples": {
                    "title": "Examples",
                    "description": "A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the `output_encoding=string`.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
                    "examples": [
                      {
                        "Example 1": {
                          "msg": "a message"
                        }
                      },
                      {
                        "Example 1": {
                          "msg": "a message"
                        },
                        "Example 2": {
                          "error": "an error message"
                        }
                      }
                    ],
                    "type": "object",
                    "additionalProperties": {
                      "title": "Example",
                      "type": [
                        "string",
                        "object",
                        "array",
                        "boolean",
                        "integer",
                        "null",
                        "number"
                      ]
                    }
                  },
                  "example_schema": {
                    "description": "A JSON schema that describes the response format for the endpoint, directly as a JSON object, or encoded as a base64 string. Use either `example` or `example_schema`, but not both.",
                    "type": [ "string", "object" ]
                  },
                  "ref": {
                    "title": "Reference",
                    "description": "The relative reference to the `components/schemas` OpenAPI definition that describes this response. Notice that the path `#/components/schemas/` is not needed.",
                    "examples": [ "your_schema_name" ],
                    "type": "string"
                  }
                },
                "patternProperties": {
                  "^[@$_#]": true
                },
                "additionalProperties": false
              }
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "servers": {
      "title": "Servers",
      "description": "The list of servers where this endpoint is hosted, when they differ from the service-level `servers`. The server URL can be a relative path, e.g., `/v1`, or an absolute URL. The URL might contain `{variables}`, although only OpenAPI recognizes them: KrakenD treats them as literal strings.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "examples": [
        [
          {
            "url": "/v1"
          }
        ],
        [
          {
            "url": "https://example.com:{port}",
            "variables": {
              "port": {
                "default": "8443",
                "enum": [ "8443", "443" ]
              }
            }
          }
        ]
      ],
      "type": "array",
      "items": {
        "type": "object",
        "required": [ "url" ],
        "properties": {
          "description": {
            "title": "Description",
            "description": "A short description of the server URL.",
            "type": "string"
          },
          "url": {
            "title": "URL",
            "description": "The URL of the server, used as the base path for this endpoint.",
            "type": [ "string", "object" ]
          },
          "variables": {
            "title": "Variables",
            "description": "A [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-variable-object) according to the OpenAPI specification. The variable name is the key and the value is the default value for that variable.",
            "type": "object",
            "patternProperties": {
              "^.*$": {
                "type": [ "string", "object" ]
              }
            }
          }
        },
        "patternProperties": {
          "^[@$_#]": true
        },
        "additionalProperties": false
      }
    },
    "summary": {
      "title": "Summary",
      "description": "A short summary for the endpoint. Use `description` for a longer explanation.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "type": "string"
    },
    "tags": {
      "title": "Tags",
      "description": "You can assign a list of tags to each API operation. If you declare tags in the `tag_definition` at the OpenAPI service level, they will have a description in the documentation. Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.\n\nSee: https://www.krakend.io/docs/enterprise/developer/openapi/",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "patternProperties": {
    "^[@$_#]": true
  },
  "additionalProperties": false
}