Swagger Models¶

Swagger models implementations

class flaskdoc.swagger.models.ApiKeySecurityScheme(name: str, description: Optional[str] = None, extensions={})¶

Bases: flaskdoc.swagger.models.SecurityScheme

OpenAPI security scheme definition with type apiKey

Example

Sample security requirements .. code-block:: json

{
“api_key”: []

}

property q_in¶

class flaskdoc.swagger.models.AuthorizationCodeOAuthFlow(authorization_url, token_url, scopes, refresh_url=None, extensions=None)¶

Bases: flaskdoc.core.ExtensionMixin

Authorization Code OAuth2 Flow

class flaskdoc.swagger.models.Callback(expression: flaskdoc.swagger.models.PathItem)¶

Bases: flaskdoc.core.ModelMixin

A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.

class flaskdoc.swagger.models.ClientCredentialsOAuthFlow(token_url, scopes, authorization_url=None, refresh_url=None, extensions=None)¶

Bases: flaskdoc.core.ExtensionMixin

Client Credentials OAuth FLow

class flaskdoc.swagger.models.ComponentType(value)¶

Bases: enum.Enum

An enumeration.

CALLBACKS = 'callbacks'¶

EXAMPLE = 'examples'¶

HEADER = 'headers'¶

LINK = 'links'¶

PARAMETER = 'parameters'¶

REQUEST_BODY = 'request+bodies'¶

RESPONSE = 'responses'¶

SCHEMA = 'schemas'¶

SECURITY_SCHEME = 'security_schemes'¶

class flaskdoc.swagger.models.Components(schemas: Optional[dict] = None, responses: Optional[dict] = None, parameters: Optional[dict] = None, examples: Optional[dict] = None, request_bodies: Optional[dict] = None, headers: Optional[dict] = None, security_schemes: Optional[dict] = None, links: Optional[dict] = None, callbacks: Optional[dict] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

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.

PATTERN = re.compile('^[a-zA-Z0-9.-_]+$')¶

add_component(component_type, components)¶

Adds components

Parameters

component_type (ComponentType) – type of component
components (dict[str, Any]) – key value mapping of components

Raises

ValueError – If key is not a valid value for regex ^[a-zA-Z0-9.-_]+$

class flaskdoc.swagger.models.Contact(name: Optional[str] = None, email: Optional[str] = None, url: Optional[str] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

Contact information for the exposed API.

This object MAY be extended with Specification Extensions.

Properties:: name: The identifying name of the contact person/organization. email: The email address of the contact person/organization. MUST be in the format of an email address. url: The URL pointing to the contact information. MUST be in the format of a URL.

validate(_, url)¶: Validates the name of all provided extensions

class flaskdoc.swagger.models.ContainerModel(items={})¶

Bases: flaskdoc.core.ModelMixin

add(key, item)¶: Adds an item :param key: item key :type key: str :param item: item :type item: dict

get(key)¶

to_dict()¶: Converts object to dictionary

class flaskdoc.swagger.models.CookieParameter(name: str, required=None, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶: Bases: flaskdoc.swagger.models.Parameter

class flaskdoc.swagger.models.DELETE(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.ExampleReference(ref: str)¶: Bases: flaskdoc.swagger.models.ReferenceObject

class flaskdoc.swagger.models.ExternalDocumentation(url: str, description: Optional[str] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

Allows referencing an external resource for extended documentation.

class flaskdoc.swagger.models.GET(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.HEAD(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.Header(required=None, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶: Bases: flaskdoc.swagger.models.HeaderParameter

class flaskdoc.swagger.models.HeaderParameter(name: str, required=None, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶: Bases: flaskdoc.swagger.models.Parameter

class flaskdoc.swagger.models.HttpMethod(value)¶

Bases: enum.Enum

An enumeration.

DELETE = 'DELETE'¶

GET = 'GET'¶

HEAD = 'HEAD'¶

OPTIONS = 'OPTIONS'¶

PATCH = 'patch'¶

POST = 'POST'¶

PUT = 'PUT'¶

TRACE = 'TRACE'¶

class flaskdoc.swagger.models.HttpSecurityScheme(scheme: string, bearer_format='bearer', description: str = None, extensions={})¶

Bases: flaskdoc.swagger.models.SecurityScheme

OpenAPI security scheme definition with type http

class flaskdoc.swagger.models.ImplicitOAuthFlow(authorization_url, scopes, token_url=None, refresh_url=None)¶

Bases: flaskdoc.core.ExtensionMixin

Implicit OAuth2 Flow

class flaskdoc.swagger.models.Info(title: str, version: str, description: Optional[str] = None, terms_of_service: Optional[str] = None, contact: Optional[flaskdoc.swagger.models.Contact] = None, license: Optional[flaskdoc.swagger.models.License] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

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. This object MAY be extended with Specification Extensions.

Properties:

title: REQUIRED. The title of the API. version: REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification

version or the API implementation version).

description: A short description of the API. CommonMark syntax MAY be used for rich text representation. terms_of_service: A URL to the Terms of Service for the API. MUST be in the format of a URL. contact: The contact information for the exposed API. license: The license information for the exposed API.

class flaskdoc.swagger.models.License(name: str, url: Optional[str] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

License information for the exposed API.

This object MAY be extended with Specification Extensions.

Properties:: name: REQUIRED. The license name used for the API. url: A URL to the license used for the API. MUST be in the format of a URL.

validate(_, url)¶: Validates the name of all provided extensions

class flaskdoc.swagger.models.Link(operation_ref: Optional[str] = None, operation_id: Optional[str] = None, description: Optional[str] = None, parameters: Optional[flaskdoc.swagger.models.SwaggerDict] = None, request_body=None, server: Optional[flaskdoc.swagger.models.Server] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

The Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

class flaskdoc.swagger.models.LinkReference(ref: str)¶: Bases: flaskdoc.swagger.models.ReferenceObject

class flaskdoc.swagger.models.OAuth2SecurityScheme(flows, extensions={})¶

Bases: flaskdoc.swagger.models.SecurityScheme

OpenAPI security scheme definition with type oauth2

class flaskdoc.swagger.models.OAuthFlow(authorization_url: str, token_url: str, refresh_url: str, scopes: {}, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

Configuration details for a supported OAuth Flow

class flaskdoc.swagger.models.OPTIONS(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.OpenApi(info, paths, version='3.0.3', tags=None, servers=None, external_docs=None, components=None)¶

Bases: flaskdoc.core.ModelMixin

This is the root document object of the OpenAPI document.

OpenApi specs tree, contains the overall specs for the API Properties:

openapi (str): Open API version used by API info (flaskdoc.swagger.info.Info): open api info object paths (Paths): Paths definitions

add_paths(paths, url_prefix=None, blp_prefix=None)¶

Updates paths to include all paths in paths :param paths: :param url_prefix: prefix :type url_prefix: str :param blp_prefix: blueprint url prefix :type blp_prefix: str

Returns:

add_server(server)¶

add_tag(tag)¶: Adds a tag to the top level spec :param tag: tag to add :type tag: swagger.Tag

class flaskdoc.swagger.models.OpenIDConnectScheme(open_id_connect_url: str, extensions={})¶

Bases: flaskdoc.swagger.models.SecurityScheme

OpenAPI security scheme definition with type openidConnect

validate(_, url)¶: Validates the name of all provided extensions

class flaskdoc.swagger.models.Operation(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin, flaskdoc.core.ApiDecoratorMixin

Describes a single API operation on a path.

add_parameter(parameter: Union[flaskdoc.swagger.models.Parameter, flaskdoc.swagger.models.ReferenceObject])¶

static from_op(http_method: str, responses: flaskdoc.swagger.models.SwaggerDict)¶: Factory for creating instances of Http Operations

property http_method¶

class flaskdoc.swagger.models.PATCH(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.POST(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.PUT(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.Parameter(name: str, required=None, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin, flaskdoc.core.ApiDecoratorMixin

Describes a single operation parameter. A unique parameter is defined by a combination of a name and location.

merge(parameter)¶

property q_in¶

property q_style¶

class flaskdoc.swagger.models.ParameterLocation(value)¶

Bases: enum.Enum

An enumeration.

COOKIE = 'cookie'¶

HEADER = 'header'¶

PATH = 'path'¶

QUERY = 'query'¶

class flaskdoc.swagger.models.PasswordOAuthFlow(token_url, scopes, authorization_url=None, refresh_url=None, extensions=None)¶

Bases: flaskdoc.core.ExtensionMixin

Password based OAuth2 Flow

class flaskdoc.swagger.models.PathItem(ref: Optional[str] = None, summary: Optional[str] = None, description: Optional[str] = None, servers: Optional[list] = None, parameters: Optional[list] = None, get: Optional[flaskdoc.swagger.models.Operation] = None, delete: Optional[flaskdoc.swagger.models.Operation] = None, head: Optional[flaskdoc.swagger.models.Operation] = None, options: Optional[flaskdoc.swagger.models.Operation] = None, patch: Optional[flaskdoc.swagger.models.Operation] = None, post: Optional[flaskdoc.swagger.models.Operation] = None, put: Optional[flaskdoc.swagger.models.Operation] = None, trace: Optional[flaskdoc.swagger.models.Operation] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

add_operation(operation)¶: Adds an operation :param operation: operation to add :type operation: Operation

add_parameter(parameter)¶

add_server(server)¶

Adds an alternative server to service all operations in this path.

Parameters: server (Server) – alternative server to add

merge_path_item(path_item)¶: Merges another path item into this on :param path_item: PathItem instance to merge :type path_item: PathItem

class flaskdoc.swagger.models.PathParameter(name: str, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶: Bases: flaskdoc.swagger.models.Parameter

class flaskdoc.swagger.models.Paths(items={})¶

Bases: flaskdoc.swagger.models.ContainerModel

Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to ACL constraints.

add(relative_url, path_item)¶: Adds a path item :param relative_url: path url name, eg /echo :type relative_url: str :param path_item: PathItem instance describing the path :type path_item: PathItem|SwaggerDict

class flaskdoc.swagger.models.QueryParameter(name: str, required=None, description: Optional[str] = None, deprecated=None, allow_empty_value=None, allow_reserved=None, schema=None, content=None, explode=None, example=None, examples: Optional[dict] = None, extensions={})¶: Bases: flaskdoc.swagger.models.Parameter

class flaskdoc.swagger.models.ReferenceObject(ref: str)¶

Bases: flaskdoc.core.ModelMixin

to_dict()¶: Converts object to dictionary

class flaskdoc.swagger.models.RelativePath(url: str, len: int = 0, params={})¶

Bases: object

parse(url_template)¶

Extracts positional parameters from url :param url_template:

Returns:

class flaskdoc.swagger.models.RequestBody(content, description: Optional[str] = None, required=None, extensions={})¶: Bases: flaskdoc.swagger.schema.ContentMixin, flaskdoc.core.ExtensionMixin

class flaskdoc.swagger.models.ResponseObject(description: str, content: Optional[flaskdoc.swagger.models.SwaggerDict] = None, headers: Optional[flaskdoc.swagger.models.SwaggerDict] = None, links: Optional[flaskdoc.swagger.models.SwaggerDict] = None, extensions={})¶

Bases: flaskdoc.swagger.schema.ContentMixin, flaskdoc.core.ExtensionMixin

Describes a single response from an API Operation, including design-time, static links to operations based on the response.

add_header(name: str, header: Union[flaskdoc.swagger.models.ReferenceObject, flaskdoc.swagger.models.HeaderParameter])¶

add_link(link_name: str, link: Union[flaskdoc.swagger.models.Link, flaskdoc.swagger.models.ReferenceObject])¶

class flaskdoc.swagger.models.ResponsesObject(default: Optional[flaskdoc.swagger.models.ResponseObject] = None, responses: Optional[dict] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The default MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call.

add_response(status_code: str, response: flaskdoc.swagger.models.ResponseObject)¶

class flaskdoc.swagger.models.SecurityScheme¶

Bases: flaskdoc.core.ExtensionMixin

Defines a security scheme that can be used by the operations.

Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2’s common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.

property q_type¶

class flaskdoc.swagger.models.SecuritySchemeType(value)¶

Bases: enum.Enum

An enumeration.

API_KEY = 'apiKey'¶

HTTP = 'http'¶

OAUTH2 = 'oauth2'¶

OPEN_ID_CONNECT = 'openIdConnect'¶

class flaskdoc.swagger.models.Server(url: str, description: Optional[str] = None, variables: Optional[dict] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

An object representing a Server.

This object MAY be extended with Specification Extensions.

Properties:

url: REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate: that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
description: An optional string describing the host designated by the URL. CommonMark syntax MAY be used for: rich text representation.
variables: A map between a variable name and its value. The value is used for substitution in the server’s: URL template.

add_variable(name: str, variable: flaskdoc.swagger.models.ServerVariable)¶: Adds a server variable :param name: variable name :param variable: Server variable instance

class flaskdoc.swagger.models.ServerVariable(default: str, enum: Optional[list] = None, description: Optional[str] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin

An object representing a Server Variable for server URL template substitution.

This object MAY be extended with Specification Extensions.

Properties:

default: REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate: value is not supplied. Note this behavior is different than the Schema Object’s treatment of default values, because in those cases parameter values are optional.

enum: An enumeration of string values to be used if the substitution options are from a limited set description: An optional description for the server variable. CommonMark syntax MAY be used for rich text

representation.

class flaskdoc.swagger.models.Style(value)¶

Bases: enum.Enum

Style values defined to aid serializing different simple parameters

DEEP_OBJECT = 'deepObject'¶

FORM = 'form'¶

LABEL = 'label'¶

MATRIX = 'matrix'¶

PIPE_DELIMITED = 'pipeDelimited'¶

SIMPLE = 'simple'¶

SPACE_DELIMITED = 'spaceDelimited'¶

class flaskdoc.swagger.models.SwaggerDict¶

Bases: collections.OrderedDict, flaskdoc.core.DictMixin

Used to filter out properties that are not set

class flaskdoc.swagger.models.TRACE(responses: dict, tags: Optional[list] = None, summary: Optional[str] = None, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, operation_id: Optional[str] = None, parameters: Optional[list] = None, request_body=None, callbacks: Optional[flaskdoc.swagger.models.SwaggerDict] = None, deprecated=None, security: Optional[list] = None, servers: Optional[list] = None, extensions={})¶

Bases: flaskdoc.swagger.models.Operation

property http_method¶

class flaskdoc.swagger.models.Tag(name: str, description: Optional[str] = None, external_docs: Optional[flaskdoc.swagger.models.ExternalDocumentation] = None, extensions={})¶

Bases: flaskdoc.core.ExtensionMixin, flaskdoc.core.ApiDecoratorMixin

external_doc(url, description=None)¶

flaskdoc.swagger.validators module¶

flaskdoc.swagger.validators.validate_url(url: str, label: str)¶