Use References for your OpenAPI configuration

Use references

To enhance your API documentation and management, utilize OpenAPI references for a clear and organized specification.

OpenAPI references allow you to define reusable components such as schemas, parameters, responses, and security definitions.

For example, you can define a schema for a data model once and reuse it across multiple endpoints.

Leveraging OpenAPI references streamlines your API development and ensures comprehensive and standardized documentation.

Plugins references

openapi.json

"components": {
    "x-cloud-apim-plugins": {
      "all": [
        {
          "enabled": true,
          "plugin": "cp:otoroshi.next.plugins.ForceHttpsTraffic"
        },
        {
          "enabled": true,
          "plugin": "cp:otoroshi.next.plugins.DisableHttp10"
        },
        {
          "enabled": true,
          "plugin": "cp:otoroshi.next.plugins.OverrideHost"
        },
        {
          "enabled": true,
          "plugin": "cp:otoroshi.next.plugins.SendOtoroshiHeadersBack"
        },
        {
          "enabled": true,
          "plugin": "cp:otoroshi.next.plugins.OtoroshiInfos",
          "config": {
            "version": "Latest",
            "ttl": 30,
            "header_name": "Otoroshi-Infos",
            "add_fields": null,
            "algo": {
              "type": "HSAlgoSettings",
              "size": 512,
              "secret": "${environment.OTOROSHI_INFOS_SIGNATURE_SECRET}",
              "base64": false
            }
          }
        },
        {
          "enabled": false,
          "plugin": "cp:otoroshi.next.plugins.Cors",
          "config": {
            "allow_origin": "*",
            "expose_headers": [],
            "allow_headers": [
              "Authorization"
            ],
            "allow_methods": [
              "GET", "PUT", "POST", "DELETE", "PATCH"
            ],
            "max_age": null,
            "allow_credentials": true
          }
        },
        {
          "plugin": "cp:otoroshi.next.plugins.ApikeyCalls",
          "enabled": true,
          "config": {
            "extractors": {
              "basic": {
                "enabled": true
              },
              "custom_headers": {
                "enabled": true
              },
              "client_id": {
                "enabled": false
              },
              "jwt": {
                "enabled": true,
                "secret_signed": true,
                "keypair_signed": true,
                "include_request_attrs": false
              },
              "oto_bearer": {
                "enabled": true
              }
            },
            "routing": {
              "enabled": false
            },
            "validate": true,
            "mandatory": true,
            "pass_with_user": false,
            "wipe_backend_request": true,
            "update_quotas": true
          }
        }
      ]
    }
  }

Backends References

openapi.json

"components": {
    "x-cloud-apim-backends": {
      "jsonplaceholder": {
        "targets": [
          {
            "hostname": "jsonplaceholder.typicode.com",
            "port": 443,
            "tls": true
          }
        ],
        "root": "/",
        "rewrite": false
      }
    }
  }

Schemas References

openapi.json

"components": {
    "schemas": {
      "Task": {
        "description": "Object representing a Task",
        "required": [
          "description"
        ],
        "type": "object",
        "properties": {
          "completed": {
            "description": "indicates if a taks is completed or not",
            "type": "boolean"
          },
          "title": {
            "description": "description of the task",
            "type": "string",
            "examples": ["My important task", "Do something"]
          },
          "id": {
            "description": "id of the task",
            "type": "integer",
            "readOnly": true,
            "format": "int32",
            "examples": [1, 2, 3, 4]
          },
          "userId": {
            "description": "id of the user that created the task",
            "type": "integer",
            "format": "int32",
            "examples": [1, 2, 3, 4]
          }
        }
      },
      "Error": {
        "description": "Object representing an error",
        "type": "object",
        "properties": {
          "code": {
            "format": "int32",
            "description": "Error code that identify of the error",
            "type": "integer",
            "examples": ["1000"]
          },
          "message": {
            "description": "Short description of the error",
            "type": "string",
            "examples": ["Could not perform the task"]
          }
        }
      }
    }
  }

How to use OpenAPI References

You can use OpenAPI references directly in your entities like this :

openapi.json

  "x-cloud-apim-backend": {
    "$ref": "#/components/x-cloud-apim-backends/jsonplaceholder"
  },
  "x-cloud-apim-plugins": {
    "$ref": "#/components/x-cloud-apim-plugins/all"
  }