{"id":7467,"library":"openapi3","title":"OpenAPI 3 Specification Client and Validator","description":"openapi3 is a Python library designed to act as both a client and validator for OpenAPI 3 Specifications. It allows developers to load OpenAPI specification files (YAML or JSON), parse them into Python objects, validate the specification's structure, and interact with the described API by calling defined operations. The library aims to provide an interactive client experience, handling authentication and parameter passing. The current version is 1.8.2, and releases are made as features are developed and bugs are fixed, though a strict cadence isn't published. The project's roadmap indicates ongoing development for richer model and parameter handling.","status":"active","version":"1.8.2","language":"en","source_language":"en","source_url":"https://github.com/dorthu/openapi3","tags":["openapi","openapi3","api client","api validator","rest","swagger"],"install":[{"cmd":"pip install openapi3","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for loading OpenAPI specifications from YAML files.","package":"PyYAML","optional":false}],"imports":[{"symbol":"OpenAPI","correct":"from openapi3 import OpenAPI"}],"quickstart":{"code":"import os\nimport yaml\nfrom openapi3 import OpenAPI\n\n# Example OpenAPI 3.0 Specification (simplified for demonstration)\n# In a real scenario, load this from a file or URL.\nspec_content = \"\"\"\nopenapi: 3.0.0\ninfo:\n  title: Example API\n  version: 1.0.0\npaths:\n  /regions:\n    get:\n      operationId: getRegions\n      summary: Get available regions\n      responses:\n        '200':\n          description: A list of regions\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  type: string\n  /secure-data:\n    get:\n      operationId: getSecureData\n      summary: Get secure data\n      security:\n        - personalAccessToken: []\n      responses:\n        '200':\n          description: Secure data\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  data:\n                    type: string\ncomponents:\n  securitySchemes:\n    personalAccessToken:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n\"\"\"\n\n# Load the spec (e.g., from a string, or a file)\nspec = yaml.safe_load(spec_content)\n\n# Parse the spec into a Python object\napi = OpenAPI(spec)\n\n# Call an operation that does not require authentication\ntry:\n    regions = api.call_getRegions()\n    print(f\"Available regions: {regions}\")\nexcept Exception as e:\n    print(f\"Error calling getRegions: {e}\")\n\n# Authenticate for operations that require it\nmy_token = os.environ.get('API_BEARER_TOKEN', 'YOUR_SUPER_SECRET_TOKEN')\nif my_token == 'YOUR_SUPER_SECRET_TOKEN':\n    print(\"Warning: Please set the API_BEARER_TOKEN environment variable for authentication.\")\n\n# Note: The `authenticate` method expects the security scheme name and the credentials.\n# For 'http' 'bearer', it typically expects the token string directly.\n# The example in docs uses `api.authenticate('personalAccessToken', my_token)` for a bearer token.\n# However, the exact usage might depend on how the spec defines the security scheme\n# and how the `openapi3` library interprets it.\n# As per the library's docs, `api.authenticate('personalAccessToken', my_token)` is correct for bearer.\n\nif my_token:\n    try:\n        api.authenticate('personalAccessToken', my_token)\n        secure_data = api.call_getSecureData()\n        print(f\"Secure data: {secure_data}\")\n    except Exception as e:\n        print(f\"Error calling getSecureData: {e}\")\nelse:\n    print(\"Skipping authenticated call as API_BEARER_TOKEN is not set.\")\n","lang":"python","description":"This quickstart demonstrates how to load an OpenAPI 3.0 specification from a string (or file), initialize the `OpenAPI` client, call an unauthenticated operation, and then authenticate to call a secured operation. It uses `PyYAML` to parse the YAML spec and `os.environ.get` for securely handling API tokens."},"warnings":[{"fix":"Review the library's GitHub roadmap and current documentation for the exact scope of automated model and validation features. Be prepared to implement custom validation or data serialization/deserialization logic for complex request bodies and parameters.","message":"The `openapi3` library's roadmap indicates that advanced features like automatic request body model generation, explicit parameter typing, and comprehensive validation for requests/responses are ongoing or future work. Users expecting full ORM-like model generation or strict runtime validation for request/response bodies and complex parameters might find current capabilities limited, requiring manual handling or external validation.","severity":"gotcha","affected_versions":"<=1.8.2"},{"fix":"Familiarize yourself with how `openapi3` represents schema objects in Python. The returned objects from API calls will expose data according to the schema, typically allowing attribute-style access (e.g., `response.data`). Refer to the library's internal `openapi.schemas` structure for understanding generated types.","message":"The library returns models that are 'of the same (generated) type' (e.g., `openapi.schemas.YourSchemaName`). While this provides a consistent interface, users expecting distinct Python classes generated for each specific schema definition in their OpenAPI spec might find the type introspection or direct attribute access less intuitive without understanding the underlying generated structure.","severity":"gotcha","affected_versions":"<=1.8.2"},{"fix":"Ensure your OpenAPI specification adheres to the OpenAPI 3.0.x standard. If encountering issues with a 3.1.x spec, consider converting it to 3.0.x or checking the library's GitHub for explicit 3.1.x support. Do not attempt to use Swagger 2.x specifications directly with this library.","message":"While `openapi3` supports OpenAPI 3 specifications, the broader ecosystem has seen updates (e.g., OpenAPI 3.1). Using a specification version not fully supported by `openapi3` or containing advanced features from newer drafts might lead to parsing errors or unexpected behavior. The library specifically targets OpenAPI 3, not older Swagger 2.x specifications.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install openapi3`","cause":"The `openapi3` library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'openapi3'"},{"fix":"Validate your `openapi.yaml` file using an online YAML validator or an OpenAPI linter (e.g., `spectral lint`). Ensure correct indentation and syntax.","cause":"The OpenAPI specification file (YAML) is malformed or contains syntax errors.","error":"yaml.scanner.ScannerError: while scanning for the next token"},{"fix":"Verify that each operation (e.g., GET, POST) in your OpenAPI spec has a unique `operationId` defined and that you are calling the corresponding `call_` method with the correct casing and spelling. For example, an `operationId: getMyResource` would be called as `api.call_getMyResource()`.","cause":"You are attempting to call an operation (`call_yourOperationId`) that is not defined with a unique `operationId` in your OpenAPI specification, or the `operationId` is misspelled. The library dynamically creates methods based on these IDs.","error":"AttributeError: 'OpenAPI' object has no attribute 'call_yourOperationId'"},{"fix":"Check your OpenAPI specification to ensure that the security scheme (e.g., `personalAccessToken`) is correctly defined under `components.securitySchemes` and that the name passed to `api.authenticate()` matches exactly.","cause":"You are trying to authenticate using a security scheme that is not defined under `components.securitySchemes` in your OpenAPI specification, or the name used in `api.authenticate()` does not match the definition.","error":"KeyError: 'securitySchemes'"}]}