[VIRTS-2887] Update Swagger Docs (#2324)

* update required schemas for all endpoints but operations

* adjust operation update schemas

* Update operation request schemas

* silence marshmallow warnings

* add summary to objects with nested sources

* silence unnecessary aiohttp apispec warnings in test server

app/api/v2/handlers/ability_api.py

@@ -36,22 +36,25 @@ async def get_ability_by_id(self, request: web.Request):
         ability = await self.get_object(request)
         return web.json_response(ability)
 
-    @aiohttp_apispec.docs(tags=['abilities'])
+    @aiohttp_apispec.docs(tags=['abilities'], summary='"name", "tactic", and "executors" are all required fields.')
     @aiohttp_apispec.request_schema(AbilitySchema)
     @aiohttp_apispec.response_schema(AbilitySchema)
     async def create_ability(self, request: web.Request):
         ability = await self.create_on_disk_object(request)
         return web.json_response(ability.display)
 
-    @aiohttp_apispec.docs(tags=['abilities'])
+    @aiohttp_apispec.docs(tags=['abilities'], summary='"name", "tactic", and "executors" are all required fields.')
     @aiohttp_apispec.request_schema(AbilitySchema(partial=True))
     @aiohttp_apispec.response_schema(AbilitySchema)
     async def create_or_update_ability(self, request: web.Request):
         ability = await self.create_or_update_on_disk_object(request)
         return web.json_response(ability.display)
 
     @aiohttp_apispec.docs(tags=['abilities'])
-    @aiohttp_apispec.request_schema(AbilitySchema(partial=True))
+    @aiohttp_apispec.request_schema(AbilitySchema(partial=True, exclude=['ability_id',
+                                                                         'requirements',
+                                                                         'additional_info',
+                                                                         'access']))
     @aiohttp_apispec.response_schema(AbilitySchema)
     async def update_ability(self, request: web.Request):
         ability = await self.update_on_disk_object(request)

app/api/v2/handlers/adversary_api.py

@@ -46,7 +46,7 @@ async def create_adversary(self, request: web.Request):
         return web.json_response(adversary.display)
 
     @aiohttp_apispec.docs(tags=['adversaries'])
-    @aiohttp_apispec.request_schema(AdversarySchema(partial=True))
+    @aiohttp_apispec.request_schema(AdversarySchema(partial=True, exclude=['adversary_id']))
     @aiohttp_apispec.response_schema(AdversarySchema)
     async def update_adversary(self, request: web.Request):
         adversary = await self.update_on_disk_object(request)

app/api/v2/handlers/agent_api.py

@@ -48,7 +48,12 @@ async def create_agent(self, request: web.Request):
         return web.json_response(agent.display)
 
     @aiohttp_apispec.docs(tags=['agents'])
-    @aiohttp_apispec.request_schema(AgentSchema(partial=True))
+    @aiohttp_apispec.request_schema(AgentSchema(partial=True, only=['group',
+                                                                    'trusted',
+                                                                    'sleep_min',
+                                                                    'sleep_max',
+                                                                    'watchdog',
+                                                                    'pending_contact']))
     @aiohttp_apispec.response_schema(AgentSchema)
     async def update_agent(self, request: web.Request):
         agent = await self.update_object(request)

app/api/v2/handlers/fact_source_api.py

@@ -43,7 +43,8 @@ async def create_fact_source(self, request: web.Request):
         source = await self.create_on_disk_object(request)
         return web.json_response(source.display)
 
-    @aiohttp_apispec.docs(tags=['sources'])
+    @aiohttp_apispec.docs(tags=['sources'], summary='All fields can be updated excluding "id" '
+                                                    'and "adjustments".')
     @aiohttp_apispec.request_schema(SourceSchema(partial=True))
     @aiohttp_apispec.response_schema(SourceSchema)
     async def update_fact_source(self, request: web.Request):

app/api/v2/handlers/objective_api.py

@@ -43,7 +43,7 @@ async def create_objective(self, request: web.Request):
         return web.json_response(objective.display)
 
     @aiohttp_apispec.docs(tags=['objectives'])
-    @aiohttp_apispec.request_schema(ObjectiveSchema(partial=True))
+    @aiohttp_apispec.request_schema(ObjectiveSchema(partial=True, exclude=['id', 'percentage']))
     @aiohttp_apispec.response_schema(ObjectiveSchema)
     async def update_objective(self, request: web.Request):
         objective = await self.update_on_disk_object(request)

app/api/v2/handlers/operation_api.py

@@ -48,15 +48,19 @@ async def get_operation_by_id(self, request: web.Request):
         operation = await self.get_object(request)
         return web.json_response(operation)
 
-    @aiohttp_apispec.docs(tags=['operations'])
-    @aiohttp_apispec.request_schema(OperationSchema)
+    @aiohttp_apispec.docs(tags=['operations'],
+                          summary='Required nested schema fields are as follows: "adversary.adversary_id", '
+                                  '"planner.planner_id", and "source.id".')
+    @aiohttp_apispec.request_schema(OperationSchema())
     @aiohttp_apispec.response_schema(OperationSchema)
     async def create_operation(self, request: web.Request):
         operation = await self.create_object(request)
         return web.json_response(operation.display)
 
     @aiohttp_apispec.docs(tags=['operations'])
-    @aiohttp_apispec.request_schema(OperationSchema(partial=True))
+    @aiohttp_apispec.request_schema(OperationSchema(partial=True, only=['state',
+                                                                        'autonomous',
+                                                                        'obfuscator']))
     @aiohttp_apispec.response_schema(OperationSchema(partial=True))
     async def update_operation(self, request: web.Request):
         operation = await self.update_object(request)
@@ -118,7 +122,7 @@ async def get_operation_link_result(self, request: web.Request):
         return web.json_response(result)
 
     @aiohttp_apispec.docs(tags=['operations'])
-    @aiohttp_apispec.request_schema(LinkSchema(partial=True))
+    @aiohttp_apispec.request_schema(LinkSchema(partial=True, only=['command', 'status']))
     @aiohttp_apispec.response_schema(LinkSchema)
     async def update_operation_link(self, request: web.Request):
         operation_id = request.match_info.get('id')
@@ -128,7 +132,9 @@ async def update_operation_link(self, request: web.Request):
         link = await self._api_manager.update_operation_link(operation_id, link_id, data, access)
         return web.json_response(link)
 
-    @aiohttp_apispec.docs(tags=['operations'])
+    @aiohttp_apispec.docs(tags=['operations'], summary='The only required fields for this endpoint are "paw", '
+                                                       '"executor.name", "executor.command", and "executor.platform". '
+                                                       '"executor.command" is expected to be unencoded.')
     @aiohttp_apispec.request_schema(LinkSchema)
     @aiohttp_apispec.response_schema(LinkSchema)
     async def create_potential_link(self, request: web.Request):

server.py

@@ -3,6 +3,7 @@
 import logging
 import os
 import sys
+import warnings
 
 import aiohttp_apispec
 from aiohttp_apispec import validation_middleware
@@ -77,6 +78,10 @@ def init_swagger_documentation(app):
     """Makes swagger documentation available at /api/docs for any endpoints
     marked for aiohttp_apispec documentation.
     """
+    warnings.filterwarnings(
+        "ignore",
+        message="Multiple schemas resolved to the name"
+    )
     aiohttp_apispec.setup_aiohttp_apispec(
         app=app,
         title='CALDERA',

tests/conftest.py

@@ -6,6 +6,7 @@
 import uuid
 import yaml
 import aiohttp_apispec
+import warnings
 
 from unittest import mock
 from aiohttp_apispec import validation_middleware
@@ -315,6 +316,11 @@ def agent_config():
 @pytest.fixture
 def api_v2_client(loop, aiohttp_client, contact_svc):
     def make_app(svcs):
+        warnings.filterwarnings(
+            "ignore",
+            message="Multiple schemas resolved to the name"
+        )
+
         app = web.Application(
             middlewares=[
                 authentication_required_middleware_factory(svcs['auth_svc']),