Improve swagger docs (#449)

advthreat/iroh#8946

Via flanders changes, adds examples to the json docs and swagger metadata.

We reuse `:default` to populate examples here. This has undesirable effects on the documentation. I reviewed the existing documentation around defaults, and many were not appropriate for user-facing docs. The closest to useful was that tlp defaults to green, but this is configurable in CTIA so that is debatable.

Instead of developing another flanders feature, I disabled default values from printing in the docs. We might want to revisit this if we actually use defaults in a user-facing way (not just generating examples).

doc/json/actor.json

@@ -1,42 +1,42 @@
 {
-  "confidence" : "string",
-  "tlp" : "string",
+  "actor_types" : [ "Cyber Espionage Operations" ],
   "aliases" : [ "string" ],
+  "confidence" : "High",
+  "description" : "string",
+  "external_ids" : [ "string" ],
+  "external_references" : [ {
+    "description" : "string",
+    "external_id" : "string",
+    "hashes" : [ "string" ],
+    "source_name" : "string",
+    "url" : "string"
+  } ],
   "id" : "string",
-  "timestamp" : "2016-01-01T01:01:01.000Z",
-  "valid_time" : {
-    "start_time" : "2016-01-01T01:01:01.000Z",
-    "end_time" : "2016-01-01T01:01:01.000Z"
-  },
-  "revision" : 10,
   "identity" : {
     "description" : "string",
     "related_identities" : [ {
+      "confidence" : "High",
       "identity" : "string",
-      "confidence" : "string",
       "information_source" : "string",
       "relationship" : "string"
     } ]
   },
-  "short_description" : "string",
-  "sophistication" : "string",
+  "intended_effect" : "Account Takeover",
+  "language" : "string",
+  "motivation" : "Ego",
   "planning_and_operational_support" : "string",
-  "schema_version" : "string",
-  "title" : "string",
+  "revision" : 10,
+  "schema_version" : "1.3.18",
+  "short_description" : "string",
+  "sophistication" : "Aspirant",
   "source" : "string",
-  "actor_types" : [ "string" ],
-  "type" : "string",
-  "intended_effect" : "string",
   "source_uri" : "string",
-  "language" : "string",
-  "external_references" : [ {
-    "source_name" : "string",
-    "description" : "string",
-    "url" : "string",
-    "hashes" : [ "string" ],
-    "external_id" : "string"
-  } ],
-  "motivation" : "string",
-  "description" : "string",
-  "external_ids" : [ "string" ]
+  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "title" : "string",
+  "tlp" : "green",
+  "type" : "actor",
+  "valid_time" : {
+    "end_time" : "2016-01-01T01:01:01.000Z",
+    "start_time" : "2016-01-01T01:01:01.000Z"
+  }
 }

doc/json/asset.json

@@ -1,27 +1,27 @@
 {
-  "tlp" : "string",
+  "asset_type" : "application",
+  "description" : "string",
+  "external_ids" : [ "string" ],
+  "external_references" : [ {
+    "description" : "string",
+    "external_id" : "string",
+    "hashes" : [ "string" ],
+    "source_name" : "string",
+    "url" : "string"
+  } ],
   "id" : "string",
-  "timestamp" : "2016-01-01T01:01:01.000Z",
-  "valid_time" : {
-    "start_time" : "2016-01-01T01:01:01.000Z",
-    "end_time" : "2016-01-01T01:01:01.000Z"
-  },
+  "language" : "string",
   "revision" : 10,
+  "schema_version" : "1.3.18",
   "short_description" : "string",
-  "schema_version" : "string",
-  "title" : "string",
   "source" : "string",
-  "type" : "string",
   "source_uri" : "string",
-  "asset_type" : "string",
-  "language" : "string",
-  "external_references" : [ {
-    "source_name" : "string",
-    "description" : "string",
-    "url" : "string",
-    "hashes" : [ "string" ],
-    "external_id" : "string"
-  } ],
-  "description" : "string",
-  "external_ids" : [ "string" ]
+  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "title" : "string",
+  "tlp" : "green",
+  "type" : "asset",
+  "valid_time" : {
+    "end_time" : "2016-01-01T01:01:01.000Z",
+    "start_time" : "2016-01-01T01:01:01.000Z"
+  }
 }

doc/json/asset_mapping.json

@@ -1,32 +1,32 @@
 {
-  "confidence" : "string",
-  "tlp" : "string",
   "asset_ref" : "string",
+  "asset_type" : "application",
+  "confidence" : "High",
+  "external_ids" : [ "string" ],
+  "external_references" : [ {
+    "description" : "string",
+    "external_id" : "string",
+    "hashes" : [ "string" ],
+    "source_name" : "string",
+    "url" : "string"
+  } ],
   "id" : "string",
-  "timestamp" : "2016-01-01T01:01:01.000Z",
-  "valid_time" : {
-    "start_time" : "2016-01-01T01:01:01.000Z",
-    "end_time" : "2016-01-01T01:01:01.000Z"
-  },
-  "revision" : 10,
-  "specificity" : "string",
+  "language" : "string",
   "observable" : {
-    "value" : "string",
-    "type" : "string"
+    "type" : "ip",
+    "value" : "1.2.3.4"
   },
-  "stability" : "string",
-  "schema_version" : "string",
+  "revision" : 10,
+  "schema_version" : "1.3.18",
   "source" : "string",
-  "type" : "string",
   "source_uri" : "string",
-  "asset_type" : "string",
-  "language" : "string",
-  "external_references" : [ {
-    "source_name" : "string",
-    "description" : "string",
-    "url" : "string",
-    "hashes" : [ "string" ],
-    "external_id" : "string"
-  } ],
-  "external_ids" : [ "string" ]
+  "specificity" : "Low",
+  "stability" : "Managed",
+  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "tlp" : "green",
+  "type" : "asset-mapping",
+  "valid_time" : {
+    "end_time" : "2016-01-01T01:01:01.000Z",
+    "start_time" : "2016-01-01T01:01:01.000Z"
+  }
 }

doc/json/asset_properties.json

@@ -1,28 +1,28 @@
 {
+  "asset_ref" : "string",
+  "external_ids" : [ "string" ],
+  "external_references" : [ {
+    "description" : "string",
+    "external_id" : "string",
+    "hashes" : [ "string" ],
+    "source_name" : "string",
+    "url" : "string"
+  } ],
+  "id" : "string",
+  "language" : "string",
   "properties" : [ {
     "name" : "string",
     "value" : "string"
   } ],
-  "tlp" : "string",
-  "asset_ref" : "string",
-  "id" : "string",
-  "timestamp" : "2016-01-01T01:01:01.000Z",
-  "valid_time" : {
-    "start_time" : "2016-01-01T01:01:01.000Z",
-    "end_time" : "2016-01-01T01:01:01.000Z"
-  },
   "revision" : 10,
-  "schema_version" : "string",
+  "schema_version" : "1.3.18",
   "source" : "string",
-  "type" : "string",
   "source_uri" : "string",
-  "language" : "string",
-  "external_references" : [ {
-    "source_name" : "string",
-    "description" : "string",
-    "url" : "string",
-    "hashes" : [ "string" ],
-    "external_id" : "string"
-  } ],
-  "external_ids" : [ "string" ]
+  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "tlp" : "green",
+  "type" : "asset-properties",
+  "valid_time" : {
+    "end_time" : "2016-01-01T01:01:01.000Z",
+    "start_time" : "2016-01-01T01:01:01.000Z"
+  }
 }

doc/json/attack_pattern.json

@@ -1,30 +1,30 @@
 {
-  "tlp" : "string",
-  "x_mitre_platforms" : [ "string" ],
-  "x_mitre_data_sources" : [ "string" ],
+  "abstraction_level" : "aggregate",
+  "description" : "string",
+  "external_ids" : [ "string" ],
+  "external_references" : [ {
+    "description" : "string",
+    "external_id" : "string",
+    "hashes" : [ "string" ],
+    "source_name" : "string",
+    "url" : "string"
+  } ],
+  "id" : "string",
   "kill_chain_phases" : [ {
     "kill_chain_name" : "string",
     "phase_name" : "string"
   } ],
-  "id" : "string",
-  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "language" : "string",
   "revision" : 10,
-  "x_mitre_contributors" : [ "string" ],
-  "abstraction_level" : "string",
+  "schema_version" : "1.3.18",
   "short_description" : "string",
-  "schema_version" : "string",
-  "title" : "string",
   "source" : "string",
-  "type" : "string",
   "source_uri" : "string",
-  "language" : "string",
-  "external_references" : [ {
-    "source_name" : "string",
-    "description" : "string",
-    "url" : "string",
-    "hashes" : [ "string" ],
-    "external_id" : "string"
-  } ],
-  "description" : "string",
-  "external_ids" : [ "string" ]
+  "timestamp" : "2016-01-01T01:01:01.000Z",
+  "title" : "string",
+  "tlp" : "green",
+  "type" : "attack-pattern",
+  "x_mitre_contributors" : [ "string" ],
+  "x_mitre_data_sources" : [ "string" ],
+  "x_mitre_platforms" : [ "string" ]
 }