fairdm.api.schema

The generated API documentation: what the schema says about the portal, and what it leaves out.

describe_api is a drf-spectacular postprocessing hook named in SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"]. It appends to the schema’s description how to authenticate, the limits and the page sizes, read from the settings and the pagination class at the moment the schema is generated, so the text cannot drift from what the portal does. It also gives the schema one tagged section for each list the portal serves, and gives each registered type’s record the description its registration holds.

Module Contents

Classes

ApiDescription	The part of the schema’s description that comes from the portal’s settings.
TypeDescription	What the registration of one sample or measurement type says about it.
TypeDocumentation	The headings of the generated documentation, and the records the types describe.
FairDMFilterExtension	Describe a list’s filters as the API applies them.
TokenSchemeExtension	Describe the token header under a name a reader of the documentation understands.

Functions

describe_api

Describe the portal in the schema: its limits, a section for each list and each type.

Data

CORE_HEADINGS
SAMPLES_HEADING
MEASUREMENTS_HEADING
KIND_DESCRIPTIONS
ACTION_TITLES

API

CORE_HEADINGS

None

SAMPLES_HEADING

‘Samples’

MEASUREMENTS_HEADING

‘Measurements’

KIND_DESCRIPTIONS

None

ACTION_TITLES

None

class ApiDescription

The part of the schema’s description that comes from the portal’s settings.

render() → str

Write the sections on authentication, limits and paging.

Returns: Markdown that follows the description a portal writes.

authentication() → str

Describe how a caller proves who they are.

Returns: A Markdown section on tokens and sessions.

limits() → str

List the request limits as the settings hold them.

Returns: A Markdown section with one line per configured rate, or an empty section when no rate is set.

paging() → str

State the default and the largest page size of a list.

Returns: A Markdown section read from the configured pagination class, or one saying a list is not paged when the portal sets none.

class TypeDescription(config: Any)

What the registration of one sample or measurement type says about it.

The generated documentation shows these words wherever it names the type: the operations, the section the type’s operations are grouped in, and the description of its record.

Initialization

Hold the registration to describe.

Args: config: The type’s :class:~fairdm.registry.ModelConfiguration.

property name: str

The type’s plural name, as the registration gives it.

property title: str

The type’s singular display name.

property heading: str

The heading the type’s operations are under: samples or measurements.

action_title(action: str) → django.utils.functional.Promise

Title one action of the type’s list or record so it can be told from the others.

Args: action: The viewset action, a key of :data:ACTION_TITLES.

Returns: The type’s plural name, then what the action does, translated when shown.

list_description() → str

Describe the type’s list with everything the registration says about it.

Returns: What the type is, then its authority, citation and keywords.

repository() → dict[str, str] | None

Point at the repository the registration names.

Returns: An OpenAPI external documentation object, or None when the registration names no repository.

summary() → str

Say what the type is.

Returns: The description in the registration’s metadata, else the registration’s own description, else the model’s docstring, else a plain sentence naming the type. The metadata comes first because a base configuration can carry a description that stands for every type built on it.

details() → str

Credit the type’s authority and citation, and list its keywords.

Returns: Markdown paragraphs for what the registration gives. A maintainer’s name and email address are never part of it.

component_names() → tuple[str, str]

Name the schema components that hold the type’s record.

Returns: The component drf-spectacular builds from the serializer, and its patched variant.

class TypeDocumentation

The headings of the generated documentation, and the records the types describe.

tags() → list[dict[str, Any]]

List a heading for each core list and custom viewset, and one for each kind of type.

Returns: OpenAPI tag objects, in the order the router serves the lists. A viewset on the router that is not generated from a registration is described by its own docstring. Sample types share one heading and measurement types another, which says what the heading holds and leaves each type’s own words to its list operation.

describe_records(components: dict[str, Any]) → None

Replace each registered type’s record description with the type’s own.

Args: components: The schema’s components.schemas, changed in place.

describe_api(result: dict[str, Any], **kwargs: Any) → dict[str, Any]

Describe the portal in the schema: its limits, a section for each list and each type.

Args: result: The generated schema. **kwargs: The generator, request and public flag drf-spectacular passes to a hook.

Returns: The schema, with its info.description extended, a top-level tags list, and each registered type’s record described by its registration.

class FairDMFilterExtension(target)

Bases: drf_spectacular.contrib.django_filters.DjangoFilterExtension

Describe a list’s filters as the API applies them.

A filter on a relation that has no short identifier is removed when the filter set is built for a request, so the schema leaves it out too.

Initialization

target_class

‘fairdm.api.filters.FairDMFilterBackend’

priority

1

resolve_filter_field(auto_schema, model, filterset_class, field_name, filter_field)

Describe a filter unless the API drops it when it builds the filter set.

class TokenSchemeExtension(target)

Bases: drf_spectacular.contrib.knox_auth_token.KnoxTokenScheme

Describe the token header under a name a reader of the documentation understands.

Initialization

priority

1

name

‘tokenAuth’

get_security_definition(auto_schema)

Add a plain description to the header scheme drf-spectacular builds.

Args: auto_schema: The schema generator’s view of the operation.

Returns: The scheme as an OpenAPI security scheme object.