ourobori.docs package

Submodules

ourobori.docs.swagger module

This module is used to create the api-documentation-creation in swagger. The function ourobori.docs.swagger.create_swagger_definition() is used in your app.py to create the documentation. The required definition of your APISPECS in your service.py can be created using the classes ourobori.docs.swagger.APISpec and ourobori.docs.swagger.OutputDefinition. If you defined everything correctly the api-documentation is available (after you started your service) at http://<YOUR_HOST>:<YOUR_PORT>/api/doc.

class ourobori.docs.swagger.APISpec(api_url, description, input_description, input_schema, output_description, output_schema, additional_output_definitions=None)[source]

Bases: object

Class representing the definition of an api to create a swagger-documentation for.

api_url

The route of the api.

description

The description for the api.

operation_id

The operation-id for the api. Should be in the form api.XXX but does nothing special.

input_description

The description of the input required by the api.

input_schema

The schema used for parsing of the request-parameters.

output_description

The description of the output created by the api.

output_schema

The schema used for parsing the output of the response of the api.

additional_output_definitions

Additional output-definitions, for example the possible errors which could be occur calling the api.

additional_output_definitions = None
get_def()[source]

Combines all relevant informations of the apispec to create a swagger-documentation in create_swagger_definition().

Returns:
The combined informations required in the form
create_swagger_definition() needs them to create a swagger-documentation.
Return type:path, definitions
class ourobori.docs.swagger.Contact(name, email, url)[source]

Bases: object

Class representing a contact to be used as parameter contact for create_swagger_definition().

name

The full name of the contact-person

email

The email of the contact-person

url

The url for the service

ourobori.docs.swagger.create_swagger_definition(rules, options, api_specs)[source]

Creates a swagger-definition based on the input-parameters and stores it in the destination_file.

Note

This function creates a local file apispec.yml in the current working directory.

Parameters:
  • protocol – The protocol of the service. Should be either 'http' or 'https'.
  • version – The version of the service.
  • title – The title to use on the documentation-page.
  • description – The description to show on the documentation-page.
  • contact – The contact for the service.
  • hostname – The hostname where the service is run.
  • port – The port the service is listening to.
  • api_specs – The apispecs to use to create the swagger-documentation.
  • destination_file – The filepath where to store the swagger-definition-file.
  • license – The license the service is licensed at.
Returns:

The location of the swagger-definition-file.

This path should be used to pass to ourobori.apps.http.run_service() inside the app.py of the service.
Return type:

swagger_definition_path
class ourobori.docs.swagger.License(name, url)[source]

Bases: object

Class representing a license to be used as parameter license for create_swagger_definition().

name

The name of the license

url

The url with license-description

class ourobori.docs.swagger.OutputDefinition(status_code, description, schema)[source]

Bases: object

Class representing an additional output-definition for an api-documentation. The definition includes the http-status-code of the output (status_code), the description for this output (description) and the content-form of the output (schema).

status_code

The http-status-code of the output.

description

The description for the ouput.

schema

The content-form of the output.

ourobori.docs.swagger_errors module

This module contains all functions, classes to create the OutputDefinitions of errors used for the creation of the swagger-documentation. It also contains already exsiting OutputDefinitions used by the BaseService.

ourobori.docs.swagger_errors.create_error_output_def(error_class, schema_class)[source]

Wrapper function to create an OutputDefinition by passing an error_class and the corresponding schema_class.

Parameters:
  • error_class – The error-class to create the OutputDefinition for.
  • schema_class – The schema-class to create the OutputDefinition for.
Returns:

The created output-definition for the error-class.
Return type:

output_definition
class ourobori.docs.swagger_errors.SErrorModel(**data)[source]

Bases: pydantic.main.BaseModel

The base-schema used for OutputDefinition for the Exceptions.

status

The http-status-code used for the exception.

data

The data contained in the exception.

Module contents