docs: Update Pydantic schema docstrings to use links instead of copied strings.

Author: dbanty

openapi_python_client/schema/openapi_schema_pydantic/components.py

@@ -18,33 +18,22 @@ class Components(BaseModel):
     Holds a set of reusable objects for different aspects of the OAS.
     All objects defined within the components object will have no effect on the API
     unless they are explicitly referenced from properties outside the components object.
+
+    References:
+        - https://swagger.io/docs/specification/components/
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject
     """
 
     schemas: Optional[Dict[str, Union[Reference, Schema]]] = None
-    """An object to hold reusable [Schema Objects](#schemaObject)."""
-
     responses: Optional[Dict[str, Union[Response, Reference]]] = None
-    """An object to hold reusable [Response Objects](#responseObject)."""
-
     parameters: Optional[Dict[str, Union[Parameter, Reference]]] = None
-    """An object to hold reusable [Parameter Objects](#parameterObject)."""
-
     examples: Optional[Dict[str, Union[Example, Reference]]] = None
-    """An object to hold reusable [Example Objects](#exampleObject)."""
-
     requestBodies: Optional[Dict[str, Union[RequestBody, Reference]]] = None
-    """An object to hold reusable [Request Body Objects](#requestBodyObject)."""
-
     headers: Optional[Dict[str, Union[Header, Reference]]] = None
-    """An object to hold reusable [Header Objects](#headerObject)."""
-
     securitySchemes: Optional[Dict[str, Union[SecurityScheme, Reference]]] = None
-    """An object to hold reusable [Security Scheme Objects](#securitySchemeObject)."""
-
     links: Optional[Dict[str, Union[Link, Reference]]] = None
-    """An object to hold reusable [Link Objects](#linkObject)."""
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {

openapi_python_client/schema/openapi_schema_pydantic/contact.py

@@ -6,26 +6,16 @@
 class Contact(BaseModel):
     """
     Contact information for the exposed API.
-    """
 
-    name: Optional[str] = None
-    """
-    The identifying name of the contact person/organization.
+    See Also:
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#contactObject
     """
 
+    name: Optional[str] = None
     url: Optional[AnyUrl] = None
-    """
-    The URL pointing to the contact information.
-    MUST be in the format of a URL.
-    """
-
     email: Optional[str] = None
-    """
-    The email address of the contact person/organization.
-    MUST be in the format of an email address.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {"name": "API Support", "url": "http://www.example.com/support", "email": "[email protected]"}

openapi_python_client/schema/openapi_schema_pydantic/discriminator.py

@@ -12,19 +12,16 @@ class Discriminator(BaseModel):
     of an alternative schema based on the value associated with it.
 
     When using the discriminator, _inline_ schemas will not be considered.
-    """
 
-    propertyName: str
-    """
-    **REQUIRED**. The name of the property in the payload that will hold the discriminator value.
+    References:
+        - https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#discriminatorObject
     """
 
+    propertyName: str
     mapping: Optional[Dict[str, str]] = None
-    """
-    An object to hold mappings between payload values and schema names or references.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {

openapi_python_client/schema/openapi_schema_pydantic/encoding.py

@@ -6,60 +6,20 @@
 
 
 class Encoding(BaseModel):
-    """A single encoding definition applied to a single schema property."""
+    """A single encoding definition applied to a single schema property.
 
-    contentType: Optional[str] = None
-    """
-    The Content-Type for encoding a specific property.
-    Default value depends on the property type:
-
-    - for `string` with `format` being `binary` – `application/octet-stream`;
-    - for other primitive types – `text/plain`;
-    - for `object` - `application/json`;
-    - for `array` – the default is defined based on the inner type.
-
-    The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`),
-    or a comma-separated list of the two types.
+    References:
+        - https://swagger.io/docs/specification/describing-request-body/
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#encodingObject
     """
 
+    contentType: Optional[str] = None
     headers: Optional[Dict[str, Reference]] = None
-    """
-    A map allowing additional information to be provided as headers, for example `Content-Disposition`.
-
-    `Content-Type` is described separately and SHALL be ignored in this section.
-    This property SHALL be ignored if the request body media type is not a `multipart`.
-    """
-
     style: Optional[str] = None
-    """
-    Describes how a specific property value will be serialized depending on its type.
-
-    See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property.
-    The behavior follows the same values as `query` parameters, including default values.
-    This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
-    """
-
     explode: bool = False
-    """
-    When this is true, property values of type `array` or `object` generate separate parameters
-    for each value of the array, or key-value-pair of the map.
-
-    For other types of properties this property has no effect.
-    When [`style`](#encodingStyle) is `form`, the default value is `true`.
-    For all other styles, the default value is `false`.
-    This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
-    """
-
     allowReserved: bool = False
-    """
-    Determines whether the parameter value SHOULD allow reserved characters,
-    as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2)
-    `:/?#[]@!$&'()*+,;=` to be included without percent-encoding.
-    The default value is `false`.
-    This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {

openapi_python_client/schema/openapi_schema_pydantic/example.py

@@ -4,35 +4,19 @@
 
 
 class Example(BaseModel):
+    """ Examples added to parameters / components to help clarify usage.
 
-    summary: Optional[str] = None
-    """
-    Short description for the example.
+    References:
+        - https://swagger.io/docs/specification/adding-examples/
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#exampleObject
     """
 
+    summary: Optional[str] = None
     description: Optional[str] = None
-    """
-    Long description for the example.
-    [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-    """
-
     value: Optional[Any] = None
-    """
-    Embedded literal example.
-    The `value` field and `externalValue` field are mutually exclusive.
-    To represent examples of media types that cannot naturally represented in JSON or YAML,
-    use a string value to contain the example, escaping where necessary.
-    """
-
     externalValue: Optional[str] = None
-    """
-    A URL that points to the literal example.
-    This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.
-
-    The `value` field and `externalValue` field are mutually exclusive.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {"summary": "A foo example", "value": {"foo": "bar"}},

openapi_python_client/schema/openapi_schema_pydantic/external_documentation.py

@@ -4,19 +4,14 @@
 
 
 class ExternalDocumentation(BaseModel):
-    """Allows referencing an external resource for extended documentation."""
+    """Allows referencing an external resource for extended documentation.
 
-    description: Optional[str] = None
-    """
-    A short description of the target documentation.
-    [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+    References:
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#externalDocumentationObject
     """
 
+    description: Optional[str] = None
     url: AnyUrl
-    """
-    **REQUIRED**. The URL for the target documentation.
-    Value MUST be in the format of a URL.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {"examples": [{"description": "Find more info here", "url": "https://example.com"}]}

openapi_python_client/schema/openapi_schema_pydantic/header.py

@@ -12,12 +12,16 @@ class Header(Parameter):
     2. `in` MUST NOT be specified, it is implicitly in `header`.
     3. All traits that are affected by the location MUST be applicable to a location of `header`
        (for example, [`style`](#parameterStyle)).
+
+    References:
+        - https://swagger.io/docs/specification/describing-parameters/#header-parameters
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#headerObject
     """
 
     name = Field(default="", const=True)
     param_in = Field(default=ParameterLocation.HEADER, const=True, alias="in")
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         allow_population_by_field_name = True
         schema_extra = {
             "examples": [

openapi_python_client/schema/openapi_schema_pydantic/info.py

@@ -11,42 +11,20 @@ class Info(BaseModel):
     The object provides metadata about the API.
     The metadata MAY be used by the clients if needed,
     and MAY be presented in editing or documentation generation tools for convenience.
-    """
 
-    title: str
-    """
-    **REQUIRED**. The title of the API.
+    References:
+        - https://swagger.io/docs/specification/api-general-info/
+        -https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject
     """
 
+    title: str
     description: Optional[str] = None
-    """
-    A short description of the API.
-    [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-    """
-
     termsOfService: Optional[AnyUrl] = None
-    """
-    A URL to the Terms of Service for the API.
-    MUST be in the format of a URL.
-    """
-
     contact: Optional[Contact] = None
-    """
-    The contact information for the exposed API.
-    """
-
     license: Optional[License] = None
-    """
-    The license information for the exposed API.
-    """
-
     version: str
-    """
-    **REQUIRED**. The version of the OpenAPI document
-    (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {

openapi_python_client/schema/openapi_schema_pydantic/license.py

@@ -6,18 +6,13 @@
 class License(BaseModel):
     """
     License information for the exposed API.
-    """
 
-    name: str
-    """
-    **REQUIRED**. The license name used for the API.
+    References:
+        - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#licenseObject
     """
 
+    name: str
     url: Optional[AnyUrl] = None
-    """
-    A URL to the license used for the API.
-    MUST be in the format of a URL.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {"examples": [{"name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html"}]}

openapi_python_client/schema/openapi_schema_pydantic/link.py

@@ -17,52 +17,20 @@ class Link(BaseModel):
     For computing links, and providing instructions to execute them,
     a [runtime expression](#runtimeExpression) is used for accessing values in an operation
     and using them as parameters while invoking the linked operation.
-    """
 
-    operationRef: Optional[str] = None
-    """
-    A relative or absolute URI reference to an OAS operation.
-    This field is mutually exclusive of the `operationId` field,
-    and MUST point to an [Operation Object](#operationObject).
-    Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject)
-    in the OpenAPI definition.
+    References:
+        - https://swagger.io/docs/specification/links/
+        - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#linkObject
     """
 
+    operationRef: Optional[str] = None
     operationId: Optional[str] = None
-    """
-    The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.
-
-    This field is mutually exclusive of the `operationRef` field.
-    """
-
     parameters: Optional[Dict[str, Any]] = None
-    """
-    A map representing parameters to pass to an operation
-    as specified with `operationId` or identified via `operationRef`.
-    The key is the parameter name to be used,
-    whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.
-
-    The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}`
-    for operations that use the same parameter name in different locations (e.g. path.id).
-    """
-
     requestBody: Optional[Any] = None
-    """
-    A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation.
-    """
-
     description: Optional[str] = None
-    """
-    A description of the link.
-    [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-    """
-
     server: Optional[Server] = None
-    """
-    A server object to be used by the target operation.
-    """
 
-    class Config:
+    class Config:  # pylint: disable=missing-class-docstring
         schema_extra = {
             "examples": [
                 {"operationId": "getUserAddressByUUID", "parameters": {"userUuid": "$response.body#/uuid"}},