Skip to content

Commit 01c9241

Browse files
emmanvgemmanvg
authored
VIRTS-3146: Add documentation for api/v2/abilities (#2402)
* add documentation for api/v2/abilities
1 parent ba85082 commit 01c9241

File tree

1 file changed

+61
-16
lines changed

1 file changed

+61
-16
lines changed

‎app/api/v2/handlers/ability_api.py

Lines changed: 61 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,46 +22,91 @@ def add_routes(self, app: web.Application):
2222
router.add_patch('/abilities/{ability_id}', self.update_ability)
2323
router.add_delete('/abilities/{ability_id}', self.delete_ability)
2424

25-
@aiohttp_apispec.docs(tags=['abilities'])
25+
@aiohttp_apispec.docs(tags=['abilities'], summary='Get all abilities.',
26+
description='Provides a list of all available abilities.')
2627
@aiohttp_apispec.querystring_schema(BaseGetAllQuerySchema)
27-
@aiohttp_apispec.response_schema(AbilitySchema(many=True, partial=True))
28+
@aiohttp_apispec.response_schema(AbilitySchema(many=True, partial=True),
29+
description='Returns a list of all abilities.')
2830
async def get_abilities(self, request: web.Request):
2931
abilities = await self.get_all_objects(request)
3032
return web.json_response(abilities)
3133

32-
@aiohttp_apispec.docs(tags=['abilities'])
34+
@aiohttp_apispec.docs(tags=['abilities'], summary='Get an ability.',
35+
description='Provides one ability based on its ability id.',
36+
parameters=[{
37+
'in': 'path',
38+
'name': 'ability_id',
39+
'schema': {'type': 'string'},
40+
'required': 'true',
41+
'description': 'UUID of the Ability to be retrieved'
42+
}])
3343
@aiohttp_apispec.querystring_schema(BaseGetOneQuerySchema)
34-
@aiohttp_apispec.response_schema(AbilitySchema(partial=True))
44+
@aiohttp_apispec.response_schema(AbilitySchema(partial=True),
45+
description='JSON dictionary representation of the existing Ability.')
3546
async def get_ability_by_id(self, request: web.Request):
3647
ability = await self.get_object(request)
3748
return web.json_response(ability)
3849

39-
@aiohttp_apispec.docs(tags=['abilities'], summary='"name", "tactic", and "executors" are all required fields.')
50+
@aiohttp_apispec.docs(tags=['abilities'], summary='Creates a new ability.',
51+
description='Creates a new adversary based on the `AbilitySchema`. '
52+
'"name", "tactic", and "executors" are all required fields.')
4053
@aiohttp_apispec.request_schema(AbilitySchema)
41-
@aiohttp_apispec.response_schema(AbilitySchema)
54+
@aiohttp_apispec.response_schema(AbilitySchema,
55+
description='JSON dictionary representation of the created Ability.')
4256
async def create_ability(self, request: web.Request):
4357
ability = await self.create_on_disk_object(request)
4458
return web.json_response(ability.display)
4559

46-
@aiohttp_apispec.docs(tags=['abilities'], summary='"name", "tactic", and "executors" are all required fields.')
60+
@aiohttp_apispec.docs(tags=['abilities'], summary='Replaces an existing ability.',
61+
description='Replaces an ability based on the `AbilitySchema` values provided '
62+
'in the message body. "name", "tactic", and "executors" '
63+
'are all required fields.',
64+
parameters=[{
65+
'in': 'path',
66+
'name': 'ability_id',
67+
'schema': {'type': 'string'},
68+
'required': 'true',
69+
'description': 'UUID of the Ability to be retrieved'
70+
}])
4771
@aiohttp_apispec.request_schema(AbilitySchema(partial=True))
48-
@aiohttp_apispec.response_schema(AbilitySchema)
72+
@aiohttp_apispec.response_schema(AbilitySchema,
73+
description='JSON dictionary representation of the replaced Ability.')
4974
async def create_or_update_ability(self, request: web.Request):
5075
ability = await self.create_or_update_on_disk_object(request)
5176
return web.json_response(ability.display)
5277

53-
@aiohttp_apispec.docs(tags=['abilities'])
54-
@aiohttp_apispec.request_schema(AbilitySchema(partial=True, exclude=['ability_id',
55-
'requirements',
56-
'additional_info',
57-
'access']))
58-
@aiohttp_apispec.response_schema(AbilitySchema)
78+
@aiohttp_apispec.docs(tags=['abilities'], summary='Updates an existing ability.',
79+
description='Updates an ability based on the `AbilitySchema` values provided '
80+
'in the message body.',
81+
parameters=[{
82+
'in': 'path',
83+
'name': 'ability_id',
84+
'schema': {'type': 'string'},
85+
'required': 'true',
86+
'description': 'UUID of the Ability to be retrieved'
87+
}])
88+
@aiohttp_apispec.request_schema(AbilitySchema(partial=True,
89+
exclude=['ability_id',
90+
'requirements',
91+
'additional_info',
92+
'access']))
93+
@aiohttp_apispec.response_schema(AbilitySchema,
94+
description='JSON dictionary representation of the replaced Ability.')
5995
async def update_ability(self, request: web.Request):
6096
ability = await self.update_on_disk_object(request)
6197
return web.json_response(ability.display)
6298

63-
@aiohttp_apispec.docs(tags=['abilities'])
64-
@aiohttp_apispec.response_schema(AbilitySchema)
99+
@aiohttp_apispec.docs(tags=['abilities'], summary='Deletes an ability.',
100+
description='Deletes an existing ability.',
101+
parameters=[{
102+
'in': 'path',
103+
'name': 'ability_id',
104+
'schema': {'type': 'string'},
105+
'required': 'true',
106+
'description': 'UUID of the Ability to be retrieved'
107+
}])
108+
@aiohttp_apispec.response_schema(AbilitySchema, code=204,
109+
description='HTTP 204 Status Code (No Content)')
65110
async def delete_ability(self, request: web.Request):
66111
await self.delete_on_disk_object(request)
67112
return web.HTTPNoContent()

0 commit comments

Comments
 (0)