nadia Tutorial¶
Basic concepts¶
The basic workflow with nadia consists of the following steps:
- Load your yaml or json specification file.
- Construct SchemaBuilder - nadia defines convenient method for creating the reasonable
one via factory
nadia.api.SchemaBuilder.create()
- Extract object definitions for which you want to create schema from the loaded dictionary.
- Construct schema for the extracted object. Note that the schema will contain top level content field.
- Use your schema to validate or serialize/deserialize objects.
Why do all schemas created by nadia have a top level content field?¶
The reason why nadia hides your real object in the content field is that
not all OpenAPI schemas can be expressed as marshmallow.Schema
.
For instance, consider the following schema:
type: array
items:
type: number
Such a data type can be modelled as marshmallow.field.List
but not as
a Schema. However, if you wrap it inside a larger object under content field, than a Schema
for such object can be constructed. This step is done automatically by nadia - even if it is
unneccesary, to make behaviour consistent for all objects.
Creating Schemabuilders¶
You can create a nadia.api.SchemaBuilder
instance in one of two ways:
- You can explicitly initialize it by passing a object providings component builders (see
nadia.builder_provider
. - You can use
nadia.api.SchemaBuilder.create
staticmethod to construct default builder using nadia’s default builder providers.