Update descriptions for response models

Materials-Consortia · Feb 28, 2020 · f8d190f · f8d190f
1 parent 245b66d
commit f8d190f
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 19 deletions.
diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json
@@ -768,7 +768,13 @@
         "type": "object",
         "properties": {
           "data": {
-            "$ref": "#/components/schemas/IndexInfoResource"
+            "title": "Data",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/IndexInfoResource"
+              }
+            ],
+            "description": "Index meta-database /info data"
           },
           "meta": {
             "title": "Meta",
@@ -1028,7 +1034,8 @@
                   "type": "object"
                 }
               }
-            ]
+            ],
+            "description": "List of unique OPTIMADE links resource objects"
           },
           "meta": {
             "title": "Meta",

diff --git a/openapi/openapi.json b/openapi/openapi.json
@@ -1161,7 +1161,13 @@
         "type": "object",
         "properties": {
           "data": {
-            "$ref": "#/components/schemas/EntryInfoResource"
+            "title": "Data",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntryInfoResource"
+              }
+            ],
+            "description": "OPTIMADE information for an entry endpoint"
           },
           "meta": {
             "title": "Meta",
@@ -1563,7 +1569,13 @@
         "type": "object",
         "properties": {
           "data": {
-            "$ref": "#/components/schemas/BaseInfoResource"
+            "title": "Data",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BaseInfoResource"
+              }
+            ],
+            "description": "The implementations /info data"
           },
           "meta": {
             "title": "Meta",
@@ -1804,7 +1816,8 @@
                   "type": "object"
                 }
               }
-            ]
+            ],
+            "description": "List of unique OPTIMADE links resource objects"
           },
           "meta": {
             "title": "Meta",
@@ -2298,7 +2311,8 @@
                   "type": "object"
                 }
               }
-            ]
+            ],
+            "description": "List of unique OPTIMADE references entry resource objects"
           },
           "meta": {
             "title": "Meta",
@@ -2368,12 +2382,17 @@
             "title": "Data",
             "anyOf": [
               {
-                "$ref": "#/components/schemas/ReferenceResource"
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ReferenceResource"
+                  }
+                ]
               },
               {
                 "type": "object"
               }
-            ]
+            ],
+            "description": "A single references entry resource"
           },
           "meta": {
             "title": "Meta",
@@ -3037,7 +3056,8 @@
                   "type": "object"
                 }
               }
-            ]
+            ],
+            "description": "List of unique OPTIMADE structures entry resource objects"
           },
           "meta": {
             "title": "Meta",
@@ -3107,12 +3127,17 @@
             "title": "Data",
             "anyOf": [
               {
-                "$ref": "#/components/schemas/StructureResource"
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/StructureResource"
+                  }
+                ]
               },
               {
                 "type": "object"
               }
-            ]
+            ],
+            "description": "A single structures entry resource"
           },
           "meta": {
             "title": "Meta",

diff --git a/optimade/models/responses.py b/optimade/models/responses.py
@@ -48,15 +48,17 @@ def data_must_be_skipped(cls, values):
 
 
 class IndexInfoResponse(Success):
-    data: IndexInfoResource = Field(...)
+    data: IndexInfoResource = Field(..., description="Index meta-database /info data")
 
 
 class EntryInfoResponse(Success):
-    data: EntryInfoResource = Field(...)
+    data: EntryInfoResource = Field(
+        ..., description="OPTIMADE information for an entry endpoint"
+    )
 
 
 class InfoResponse(Success):
-    data: BaseInfoResource = Field(...)
+    data: BaseInfoResource = Field(..., description="The implementations /info data")
 
 
 class EntryResponseOne(Success):
@@ -77,25 +79,35 @@ class EntryResponseMany(Success):
 
 class LinksResponse(EntryResponseMany):
     data: Union[List[LinksResource], List[Dict[str, Any]]] = Field(
-        ..., uniqueItems=True
+        ...,
+        description="List of unique OPTIMADE links resource objects",
+        uniqueItems=True,
     )
 
 
 class StructureResponseOne(EntryResponseOne):
-    data: Union[StructureResource, Dict[str, Any], None] = Field(...)
+    data: Union[StructureResource, Dict[str, Any], None] = Field(
+        ..., description="A single structures entry resource"
+    )
 
 
 class StructureResponseMany(EntryResponseMany):
     data: Union[List[StructureResource], List[Dict[str, Any]]] = Field(
-        ..., uniqueItems=True
+        ...,
+        description="List of unique OPTIMADE structures entry resource objects",
+        uniqueItems=True,
     )
 
 
 class ReferenceResponseOne(EntryResponseOne):
-    data: Union[ReferenceResource, Dict[str, Any], None] = Field(...)
+    data: Union[ReferenceResource, Dict[str, Any], None] = Field(
+        ..., description="A single references entry resource"
+    )
 
 
 class ReferenceResponseMany(EntryResponseMany):
     data: Union[List[ReferenceResource], List[Dict[str, Any]]] = Field(
-        ..., uniqueItems=True
+        ...,
+        description="List of unique OPTIMADE references entry resource objects",
+        uniqueItems=True,
     )