Metadata-Version: 2.1
Name: openapi-schema-pydantic
Version: 0.2.1
Summary: OpenAPI (v3) specification schema as pydantic class
Home-page: https://github.com/kuimono/openapi-schema-pydantic
Author: Kuimono
License: UNKNOWN
Description: # openapi-schema-pydantic
        
        [![PyPI](https://img.shields.io/pypi/v/openapi-schema-pydantic)](https://pypi.org/project/openapi-schema-pydantic/)
        [![PyPI - License](https://img.shields.io/pypi/l/openapi-schema-pydantic)](https://github.com/kuimono/openapi-schema-pydantic/blob/master/LICENSE)
        
        OpenAPI (v3) specification schema as [Pydantic](https://github.com/samuelcolvin/pydantic) classes.
        
        The naming of the classes follows the schema in 
        [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schema).
        
        ## Installation
        
        `pip install openapi-schema-pydantic`
        
        ## Try me
        
        ```python
        from openapi_schema_pydantic import OpenAPI, Info, PathItem, Operation, Response
        
        # Construct OpenAPI by pydantic objects
        open_api = OpenAPI(
            info=Info(
                title="My own API",
                version="v0.0.1",
            ),
            paths={
                "/ping": PathItem(
                    get=Operation(
                        responses={
                            "200": Response(
                                description="pong"
                            )
                        }
                    )
                )
            },
        )
        print(open_api.json(by_alias=True, exclude_none=True, indent=2))
        ```
        
        Result:
        
        ```json
        {
          "openapi": "3.0.3",
          "info": {
            "title": "My own API",
            "version": "v0.0.1"
          },
          "servers": [
            {
              "url": "/"
            }
          ],
          "paths": {
            "/ping": {
              "get": {
                "responses": {
                  "200": {
                    "description": "pong"
                  }
                },
                "deprecated": false
              }
            }
          }
        }
        ```
        
        ## Take advantage of Pydantic
        
        Pydantic is a great tool, allow you to use object / dict / mixed data for for input.
        
        The following examples give the same OpenAPI result as above:
        
        ```python
        from openapi_schema_pydantic import OpenAPI, PathItem, Response
        
        # Construct OpenAPI from dict
        open_api = OpenAPI.parse_obj({
            "info": {"title": "My own API", "version": "v0.0.1"},
            "paths": {
                "/ping": {
                    "get": {"responses": {"200": {"description": "pong"}}}
                }
            },
        })
        
        # Construct OpenAPI with mix of dict/object
        open_api = OpenAPI.parse_obj({
            "info": {"title": "My own API", "version": "v0.0.1"},
            "paths": {
                "/ping": PathItem(
                    get={"responses": {"200": Response(description="pong")}}
                )
            },
        })
        ```
        
        ## Use Pydantic classes as schema
        
        - The [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject)
          in OpenAPI has definitions and tweaks in JSON Schema, which is hard to comprehend and define a good data class
        - Pydantic already has a good way to [create JSON schema](https://pydantic-docs.helpmanual.io/usage/schema/),
          let's not re-invent the wheel
          
        The approach to deal with this:
        
        1. Use `PydanticSchema` objects to represent the `Schema` in `OpenAPI` object
        2. Invoke `construct_open_api_with_schema_class` to resolve the JSON schemas and references
        
        ```python
        from pydantic import BaseModel, Field
        
        from openapi_schema_pydantic import OpenAPI
        from openapi_schema_pydantic.util import PydanticSchema, construct_open_api_with_schema_class
        
        def construct_base_open_api() -> OpenAPI:
            return OpenAPI.parse_obj({
                "info": {"title": "My own API", "version": "v0.0.1"},
                "paths": {
                    "/ping": {
                        "post": {
                            "requestBody": {"content": {"application/json": {
                                "schema": PydanticSchema(schema_class=PingRequest)
                            }}},
                            "responses": {"200": {
                                "description": "pong",
                                "content": {"application/json": {
                                    "schema": PydanticSchema(schema_class=PingResponse)
                                }},
                            }},
                        }
                    }
                },
            })
        
        class PingRequest(BaseModel):
            """Ping Request"""
            req_foo: str = Field(description="foo value of the request")
            req_bar: str = Field(description="bar value of the request")
        
        class PingResponse(BaseModel):
            """Ping response"""
            resp_foo: str = Field(description="foo value of the response")
            resp_bar: str = Field(description="bar value of the response")
        
        open_api = construct_base_open_api()
        open_api = construct_open_api_with_schema_class(open_api)
        
        # print the result openapi.json
        print(open_api.json(by_alias=True, exclude_none=True, indent=2))
        ```
        
        Result:
        
        ```json
        {
          "openapi": "3.0.3",
          "info": {
            "title": "My own API",
            "version": "v0.0.1"
          },
          "servers": [
            {
              "url": "/"
            }
          ],
          "paths": {
            "/ping": {
              "post": {
                "requestBody": {
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/PingRequest"
                      }
                    }
                  },
                  "required": false
                },
                "responses": {
                  "200": {
                    "description": "pong",
                    "content": {
                      "application/json": {
                        "schema": {
                          "$ref": "#/components/schemas/PingResponse"
                        }
                      }
                    }
                  }
                },
                "deprecated": false
              }
            }
          },
          "components": {
            "schemas": {
              "PingRequest": {
                "title": "PingRequest",
                "required": [
                  "req_foo",
                  "req_bar"
                ],
                "type": "object",
                "properties": {
                  "req_foo": {
                    "title": "Req Foo",
                    "type": "string",
                    "description": "foo value of the request"
                  },
                  "req_bar": {
                    "title": "Req Bar",
                    "type": "string",
                    "description": "bar value of the request"
                  }
                },
                "description": "Ping Request"
              },
              "PingResponse": {
                "title": "PingResponse",
                "required": [
                  "resp_foo",
                  "resp_bar"
                ],
                "type": "object",
                "properties": {
                  "resp_foo": {
                    "title": "Resp Foo",
                    "type": "string",
                    "description": "foo value of the response"
                  },
                  "resp_bar": {
                    "title": "Resp Bar",
                    "type": "string",
                    "description": "bar value of the response"
                  }
                },
                "description": "Ping response"
              }
            }
          }
        }
        ```
        
        ## Notes
        
        ### Use of OpenAPI.json()
        
        When using `OpenAPI.json()` function, arguments `by_alias=True, exclude_none=True` has to be in place.
        Otherwise the result json will not fit the OpenAPI standard.
        
        ```python
        # OK
        open_api.json(by_alias=True, exclude_none=True, indent=2)
        
        # Not good
        open_api.json(indent=2)
        ```
        
        More info about field alias:
        
        | OpenAPI version | Field alias info |
        | --------------- | ---------------- |
        | 3.0.3 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_0_3/README.md#alias) |
        
        ### Non-pydantic schema types
        
        Some schema types are not implemented as pydantic classes.
        Please refer to the following for more info:
        
        | OpenAPI version | Non-pydantic schema type info |
        | --------------- | ----------------------------- |
        | 3.0.3 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_0_3/README.md#non-pydantic-schema-types) |
        
        ## License
        
        [MIT License](https://github.com/kuimono/openapi-schema-pydantic/blob/master/LICENSE)
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
