From 7f8b405537ca12c5734d43b2ea80565f76c71e28 Mon Sep 17 00:00:00 2001
From: schroeder5 <s.schroeder@fz-juelich.de>
Date: Mon, 3 Aug 2020 20:07:14 +0200
Subject: [PATCH] #11: started adding descriptive text for automatic openapi
documentation (especially for use documenting metadata)
---
toardb/contacts/schemas.py | 32 ++++++----
toardb/timeseries/schemas.py | 30 +++++----
toardb/variables/schemas.py | 14 ++---
toardb_fastapi.md | 118 +++++++++++++++++------------------
4 files changed, 102 insertions(+), 92 deletions(-)
diff --git a/toardb/contacts/schemas.py b/toardb/contacts/schemas.py
index 296b88a..da376c4 100644
--- a/toardb/contacts/schemas.py
+++ b/toardb/contacts/schemas.py
@@ -5,19 +5,19 @@ Pydantic schemas for TOAR database
from typing import List, Dict, Any
-from pydantic import BaseModel, validator
+from pydantic import BaseModel, validator, Field
from .models import OK_enum
class OrganisationBase(BaseModel):
id: int = None
- name: str
- longname: str
- kind: str
- city: str
- postcode: str
- street_address: str
- country: str
- homepage: str
+ name: str = Field(..., description="Short name (abbreviation) of organisation")
+ longname: str = Field(..., description="Long name of organisation")
+ kind: str = Field(..., description="Kind of organisation")
+ city: str = Field(..., description="City where organisation resides")
+ postcode: str = Field(..., description="Postcode of organisation city")
+ street_address: str = Field(..., description="Street address of organisation city")
+ country: str = Field(..., description="Country to which organisation belongs")
+ homepage: str = Field(..., description="Homepage of organisation")
@validator('kind')
def check_kind(cls, v):
@@ -45,11 +45,17 @@ class Organisation(OrganisationBase):
class PersonBase(BaseModel):
id: int = None
- name: str
- email: str
- phone: str
- isprivate: bool
+ name: str = Field(..., description="Name of person")
+ email: str = Field(..., description="Email address of person")
+ phone: str = Field(..., description="Phone number of person")
+ isprivate: bool = Field(..., description="Set this flag to true if the contact details shall not be exposed publicly")
+
+ def __str__(self):
+ return f"{self.name} <{self.email}>"
+ class Meta:
+ db_table = 'persons'
+# app_label = 'Person'
class PersonCreate(PersonBase):
pass
diff --git a/toardb/timeseries/schemas.py b/toardb/timeseries/schemas.py
index 75d0637..f8a7584 100644
--- a/toardb/timeseries/schemas.py
+++ b/toardb/timeseries/schemas.py
@@ -6,7 +6,7 @@ Pydantic schemas for TOAR database
from typing import List, Any
-from pydantic import BaseModel, Json, validator
+from pydantic import BaseModel, Json, validator, Field
import datetime as dt
from toardb.generic.models import RS_enum, RC_enum
from toardb.contacts.models import Contact
@@ -24,19 +24,23 @@ from toardb.stationmeta.schemas import StationmetaCoreStub
class TimeseriesCoreBaseStub(BaseModel):
id: int = None
- label: str
- order: int
- access_rights: str
- sampling_frequency: str
- aggregation: str
+ label: str = Field(..., description="a short string to distinguish this timeseries from others with the same combination of station and variable")
+ order: int = Field(..., description="indicates position of this timeseries in a list when several timeseries share the same station and variable combination")
+ access_rights: str = Field(..., description="Access rights of timeseries data")
+ sampling_frequency: str = Field(..., description="Sampling frequency of data in this timeseries")
+ aggregation: str = Field(..., description="Aggregation type in this timeseries")
source: str
- data_start_date: dt.datetime
- data_end_date: dt.datetime
- measurement_method: str
- sampling_height: float
- date_added: dt.datetime
- date_modified: dt.datetime
- additional_metadata: Json
+ data_start_date: dt.datetime = Field(..., description="Start date of the variable data available for this station")
+ data_end_date: dt.datetime = Field(..., description="End date of the variable data available for this station")
+ measurement_method: str = Field(..., description="instrument principle of measurement")
+ sampling_height: float = Field(..., description="Height above the ground of the inlet/instrument/sampler (in m)")
+ date_added: dt.datetime = Field(..., description="Date of timeseries metadata entry into TOAR database")
+ date_modified: dt.datetime = Field(..., description="Date of last timeseries metadata modification")
+ additional_metadata: Json = Field(..., description="Additional information about the timeseries as JSON structure.")
+
+# still missing: "Score values from automated data QA (5-star evaluation)"
+# still missing: "detailed report of timeseries QA/QC evaluation"
+# still missing: "arbitrary additional information about this timeseries"
@validator('access_rights')
def check_access_rights(cls, v):
diff --git a/toardb/variables/schemas.py b/toardb/variables/schemas.py
index e251ace..c8d6de3 100644
--- a/toardb/variables/schemas.py
+++ b/toardb/variables/schemas.py
@@ -5,16 +5,16 @@ Pydantic schemas for TOAR database
from typing import List
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
class VariableBase(BaseModel):
- name: str
- longname: str
- displayname: str
- cf_standardname: str
- units: str
- chemical_formula: str
+ name: str = Field(..., description="Name. Short variable-like name of the variable")
+ longname: str = Field(..., description="Longname. Long (explicit) name of the variable")
+ displayname: str = Field(..., description="Displayname. Display name of the variable")
+ cf_standardname: str = Field(..., description="Cf standardname. CF standard name of the variable if defined")
+ units: str = Field(..., description="Units. Physical units of variable")
+ chemical_formula: str = Field(..., description="Chemical formula. Chemical formula of variable(if applicable)")
class VariableCreate(VariableBase):
pass
diff --git a/toardb_fastapi.md b/toardb_fastapi.md
index 3c97336..8ac9a5f 100644
--- a/toardb_fastapi.md
+++ b/toardb_fastapi.md
@@ -518,48 +518,48 @@ Get Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | Yes |
-| name | string | | Yes |
-| longname | string | | Yes |
-| kind | string | | Yes |
-| city | string | | Yes |
-| postcode | string | | Yes |
-| street_address | string | | Yes |
-| country | string | | Yes |
-| homepage | string | | Yes |
+| name | string | Short name (abbreviation) of organisation | Yes |
+| longname | string | Long name of organisation | Yes |
+| kind | string | Kind of organisation | Yes |
+| city | string | City where organisation resides | Yes |
+| postcode | string | Postcode of organisation city | Yes |
+| street_address | string | Street address of organisation city | Yes |
+| country | string | Country to which organisation belongs | Yes |
+| homepage | string | Homepage of organisation | Yes |
#### OrganisationCreate
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | No |
-| name | string | | Yes |
-| longname | string | | Yes |
+| name | string | Short name (abbreviation) of organisation | Yes |
+| longname | string | Long name of organisation | Yes |
| kind | string | | Yes |
-| city | string | | Yes |
-| postcode | string | | Yes |
-| street_address | string | | Yes |
-| country | string | | Yes |
-| homepage | string | | Yes |
+| city | string | City where organisation resides | Yes |
+| postcode | string | Postcode of organisation city | Yes |
+| street_address | string | Street address of organisation city | Yes |
+| country | string | Country to which organisation belongs | Yes |
+| homepage | string | Homepage of organisation | Yes |
#### Person
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | Yes |
-| name | string | | Yes |
-| email | string | | Yes |
-| phone | string | | Yes |
-| isprivate | boolean | | Yes |
+| name | string | Name of person | Yes |
+| email | string | Email address of person | Yes |
+| phone | string | Phone number of person | Yes |
+| isprivate | boolean | Set this flag to true if the contact details shall not be exposed publicly | Yes |
#### PersonCreate
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | No |
-| name | string | | Yes |
-| email | string | | Yes |
-| phone | string | | Yes |
-| isprivate | boolean | | Yes |
+| name | string | Name of person | Yes |
+| email | string | Email address of person | Yes |
+| phone | string | Phone number of person | Yes |
+| isprivate | boolean | Set this flag to true if the contact details shall not be exposed publicly | Yes |
#### Stationmeta
@@ -751,19 +751,19 @@ Get Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | Yes |
-| label | string | | Yes |
-| order | integer | | Yes |
-| access_rights | string | | Yes |
-| sampling_frequency | string | | Yes |
-| aggregation | string | | Yes |
+| label | string | a short string to distinguish this timeseries from others with the same combination of station and variable | Yes |
+| order | integer | indicates position of this timeseries in a list when several timeseries share the same station and variable combination | Yes |
+| access_rights | string | Access rights of timeseries data | Yes |
+| sampling_frequency | string | Sampling frequency of data in this timeseries | Yes |
+| aggregation | string | Aggregation type in this timeseries | Yes |
| source | string | | Yes |
-| data_start_date | dateTime | | Yes |
-| data_end_date | dateTime | | Yes |
-| measurement_method | string | | Yes |
-| sampling_height | number | | Yes |
-| date_added | dateTime | | Yes |
-| date_modified | dateTime | | Yes |
-| additional_metadata | string (json-string) | | No |
+| data_start_date | dateTime | Start date of the variable data available for this station | Yes |
+| data_end_date | dateTime | End date of the variable data available for this station | Yes |
+| measurement_method | string | instrument principle of measurement | Yes |
+| sampling_height | number | Height above the ground of the inlet/instrument/sampler (in m) | Yes |
+| date_added | dateTime | Date of timeseries metadata entry into TOAR database | Yes |
+| date_modified | dateTime | Date of last timeseries metadata modification | Yes |
+| additional_metadata | string (json-string) | Additional information about the timeseries as JSON structure. | Yes |
| roles | [ [TimeseriesRole](#timeseriesrole) ] | | No |
| annotations | [ [TimeseriesAnnotation](#timeseriesannotation) ] | | No |
| variable | [Variable](#variable) | | Yes |
@@ -787,19 +787,19 @@ Get Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | integer | | No |
-| label | string | | Yes |
-| order | integer | | Yes |
-| access_rights | string | | Yes |
-| sampling_frequency | string | | Yes |
-| aggregation | string | | Yes |
+| label | string | a short string to distinguish this timeseries from others with the same combination of station and variable | Yes |
+| order | integer | indicates position of this timeseries in a list when several timeseries share the same station and variable combination | Yes |
+| access_rights | string | Access rights of timeseries data | Yes |
+| sampling_frequency | string | Sampling frequency of data in this timeseries | Yes |
+| aggregation | string | Aggregation type in this timeseries | Yes |
| source | string | | Yes |
-| data_start_date | dateTime | | Yes |
-| data_end_date | dateTime | | Yes |
-| measurement_method | string | | Yes |
-| sampling_height | number | | Yes |
-| date_added | dateTime | | Yes |
-| date_modified | dateTime | | Yes |
-| additional_metadata | string (json-string) | | No |
+| data_start_date | dateTime | Start date of the variable data available for this station | Yes |
+| data_end_date | dateTime | End date of the variable data available for this station | Yes |
+| measurement_method | string | instrument principle of measurement | Yes |
+| sampling_height | number | Height above the ground of the inlet/instrument/sampler (in m) | Yes |
+| date_added | dateTime | Date of timeseries metadata entry into TOAR database | Yes |
+| date_modified | dateTime | Date of last timeseries metadata modification | Yes |
+| additional_metadata | string (json-string) | Additional information about the timeseries as JSON structure. | Yes |
| station_id | integer | | Yes |
| variable_id | integer | | Yes |
| programme_id | integer | | Yes |
@@ -846,21 +846,21 @@ Get Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
-| name | string | | Yes |
-| longname | string | | Yes |
-| displayname | string | | Yes |
-| cf_standardname | string | | Yes |
-| units | string | | Yes |
-| chemical_formula | string | | Yes |
+| name | string | Name. Short variable-like name of the variable | Yes |
+| longname | string | Longname. Long (explicit) name of the variable | Yes |
+| displayname | string | Displayname. Display name of the variable | Yes |
+| cf_standardname | string | Cf standardname. CF standard name of the variable if defined | Yes |
+| units | string | Units. Physical units of variable | Yes |
+| chemical_formula | string | Chemical formula. Chemical formula of variable(if applicable) | Yes |
| id | integer | | Yes |
#### VariableCreate
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
-| name | string | | Yes |
-| longname | string | | Yes |
-| displayname | string | | Yes |
-| cf_standardname | string | | Yes |
-| units | string | | Yes |
-| chemical_formula | string | | Yes |
+| name | string | Name. Short variable-like name of the variable | Yes |
+| longname | string | Longname. Long (explicit) name of the variable | Yes |
+| displayname | string | Displayname. Display name of the variable | Yes |
+| cf_standardname | string | Cf standardname. CF standard name of the variable if defined | Yes |
+| units | string | Units. Physical units of variable | Yes |
+| chemical_formula | string | Chemical formula. Chemical formula of variable(if applicable) | Yes |
\ No newline at end of file
--
GitLab