Skip to content

Commit 713cea1

Browse files
tora-kozictora-kozic
authored
update unified API documentation file to openAPI 3.0 (#129)
1 parent e25ecef commit 713cea1

File tree

5 files changed

+148
-166
lines changed

5 files changed

+148
-166
lines changed

‎build-scripts/extract_open_api_paths_and_definitions.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ main() {
77
local docs_src="${2:?Missing param docs_src at index 2.}"
88
json_docs=$(find ${docs} \! -name '*.yaml' -type f)
99
jq -s '.[].paths' $json_docs | jq -s add > ${docs_src}/paths.json
10-
jq -s '.[].definitions' $json_docs | jq -s add > ${docs_src}/defs.json
10+
jq -s '.[].components.schemas' $json_docs | jq -s add > ${docs_src}/defs.json
1111
}
1212

1313
main "$@"

‎build-scripts/make_unified_open_api_doc.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ main() {
77
local docs_out="${2:?Missing param docs_out at index 2.}"
88
local api_docs="${3:?Missing param api_docs at index 3.}"
99
jq '.paths |= $paths' --argfile paths ${docs_src}/paths.json swagger_template.json > ${docs_src}/merged_paths.json
10-
jq '.definitions |= $defs' --argfile defs ${docs_src}/defs.json ${docs_src}/merged_paths.json > ${docs_out}/code42api.json
10+
jq '.components.schemas |= $defs' --argfile defs ${docs_src}/defs.json ${docs_src}/merged_paths.json > ${docs_out}/code42api.json
1111

1212
sed -i.bak 's/x-deprecated/deprecated/g' "${docs_out}/code42api.json" && rm "${docs_out}/code42api.json.bak"
1313

‎build-scripts/transform.sh

+64-111
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,70 @@
11
#!/bin/bash
22

33
main() {
4-
local docs="${1:?Missing param docs at index 1.}"
5-
TMP=.transform.tmp
6-
ALERTS="${docs}/alerts"
7-
AUTHORITY="${docs}/authority.json"
8-
RULES_V1="${docs}/alert-rules"
9-
RULES_V2="${docs}/alert-rules-v2"
10-
TRUSTED_ACTIVITIES_V2="${docs}/trusted-activities.json"
11-
FILE_EVENTS="${docs}/file-events.json"
12-
CASES="${docs}/cases.json"
13-
ACTORS="${docs}/actors.json"
14-
15-
echo "Applying transformations..."
16-
17-
### Audit log
18-
echo "Transforming Audit Log docs..."
19-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/audit > ${docs}/audit.json
20-
rm ${docs}/audit
21-
22-
### Authority
23-
echo "Transforming Authority docs..."
24-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/authority > $AUTHORITY
25-
# The authority's File component schema overwrites FFS', rename it
26-
### SWAGGER 2 ###
27-
jq '.definitions |= with_entries( if .key == "File" then .key |= "AuthorityFile" else . end)' < $AUTHORITY > $TMP && mv $TMP $AUTHORITY
28-
jq '.definitions.RestoreGroup.properties.files.items."$ref" |= "#/definitions/AuthorityFile"' < $AUTHORITY > $TMP && mv $TMP $AUTHORITY
29-
30-
### OPENAPI 3 ###
31-
# jq '.components.schemas |= with_entries( if .key == "File" then .key |= "AuthorityFile" else . end)' < ${docs}/authority > $AUTHORITY
32-
# jq '.components.schemas.RestoreGroup.properties.files.items."$ref" |= "#/components/schemas/AuthorityFile"' < $AUTHORITY > $TMP && mv $TMP $AUTHORITY
33-
34-
rm ${docs}/authority
35-
36-
### Trusted Activities v2
37-
echo "Transforming Trusted Activities docs..."
38-
# convert openapi 3 yaml to swagger 2 json
39-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/trusted-activities > $TRUSTED_ACTIVITIES_V2
40-
rm "${docs}/trusted-activities"
41-
42-
### File Events
43-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/file-events > $FILE_EVENTS
44-
echo "Transforming File Events docs..."
45-
# prefix v1 summary fields with "v1" and mark as deprecated
46-
jq '.paths |= with_entries( if .key | contains("v1") then .value[].summary |= "v1 - \(.)" else . end)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
47-
jq '.paths |= with_entries( if .key | contains("v1") then .value[].deprecated |= true else . end)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
48-
# prefix v2 summary fields with "v2"
49-
jq '.paths |= with_entries( if .key | contains("v2") then (if .value.post? then .value.post.summary |= "v2 - \(.)" else .value.get.summary |= "v2 - \(.)" end) else . end)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
50-
# order v2 events before v1
51-
jq '.paths |= (to_entries | [_nwise(.; 5)] | reverse | flatten | from_entries)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
52-
rm ${docs}/file-events
53-
mv $FILE_EVENTS ${docs}/file-events
54-
55-
### Alert Rules v1
56-
echo "Transforming Alert Rule v1 docs..."
57-
# prefix summary fields with "v1"
58-
jq '.paths[][].summary |= "v1 - \(.)"' < $RULES_V1 > $TMP && mv $TMP $RULES_V1
59-
# mark v1 endpoints as deprecated
60-
jq '.paths[][].deprecated = true'< $RULES_V1 > $TMP && mv $TMP $RULES_V1
61-
# deprecate alert API query rules endpoint
62-
jq '.paths[][] |= if .tags == [ "Rules" ] then .deprecated = true else . end' < $ALERTS > $TMP && mv $TMP $ALERTS
63-
jq '.paths[][].tags[] |= if . == "Rules" then "Alerts" else . end' < $ALERTS > $TMP && mv $TMP $ALERTS
64-
65-
### Alert Rules v2
66-
echo "Transforming Alert Rule v2 docs..."
67-
# mark rules summary fields with "v2"
68-
jq '.paths[][].summary |= "v2 - \(.)"' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
69-
# hide add-users
70-
jq 'del(.paths."/v2/alert-rules/{id}/users".post)' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
71-
# hide remove-users
72-
jq 'del(.paths."/v2/alert-rules/{id}/remove-users")' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
73-
# hide remove-user-aliases
74-
jq 'del(.paths."/v2/alert-rules/{id}/remove-user-aliases")' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
75-
76-
## Sessions
77-
echo "Transforming Sessions docs..."
78-
# convert openapi 3 yaml to swagger 2 json
79-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/sessions > "${docs}/sessions.json"
80-
rm ${docs}/sessions
81-
82-
### Watchlists
83-
echo "Transforming Department docs..."
84-
# convert openapi 3 yaml to swagger 2 json
85-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/departments > "${docs}/departments.json"
86-
rm ${docs}/departments
87-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/directory-groups > "${docs}/directory-groups.json"
88-
rm ${docs}/directory-groups
89-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/watchlists > "${docs}/watchlists.json"
90-
rm ${docs}/watchlists
91-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/risk-profiles > "${docs}/risk-profiles.json"
92-
rm ${docs}/risk-profiles
93-
94-
# set update-risk-profile PATCH description
95-
echo "Transforming Risk Profile docs..."
96-
jq '.paths."/v2/actor-risk-profiles/{actor_id}".patch.description |= {"$ref": "./api-descriptions/user_risk_profile_patch.rmd"}' < "${docs}/risk-profiles.json" > $TMP && mv $TMP "${docs}/risk-profiles.json"
97-
98-
### Cases
99-
echo "Transforming Cases docs..."
100-
# convert openapi 3 yaml to swagger 2 json
101-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/cases > $CASES
102-
rm ${docs}/cases
103-
mv $CASES ${docs}/cases
104-
105-
### Actors
106-
echo "Transforming Actor docs..."
107-
# convert openapi 3 yaml to swagger 2 json
108-
api-spec-converter -f openapi_3 -t swagger_2 -c ${docs}/actor-enrichment-service > $ACTORS
109-
rm ${docs}/actor-enrichment-service
110-
# rename tags
111-
jq '.paths[][].tags[] |=
112-
if . == "actor-api-controller" then "Actors" else .
113-
end' < $ACTORS > $TMP && mv $TMP $ACTORS
114-
mv $ACTORS ${docs}/actors
4+
local docs="${1:?Missing param docs at index 1.}"
5+
TMP=.transform.tmp
6+
7+
echo "Applying transformations..."
8+
9+
### Alerts
10+
ALERTS="${docs}/alerts"
11+
echo "Transforming Alerts docs..."
12+
# deprecate alert API query rules endpoint
13+
jq '.paths[][] |= if .tags == [ "Rules" ] then .deprecated = true else . end' < $ALERTS > $TMP && mv $TMP $ALERTS
14+
jq '.paths[][].tags[] |= if . == "Rules" then "Alerts" else . end' < $ALERTS > $TMP && mv $TMP $ALERTS
15+
api-spec-converter -f swagger_2 -t openapi_3 -s json -c $ALERTS > ${docs}/alerts.json
16+
rm "$ALERTS"
17+
18+
### Authority
19+
AUTHORITY="${docs}/authority.json"
20+
echo "Transforming Authority docs..."
21+
### OPENAPI 3 ###
22+
jq '.components.schemas |= with_entries( if .key == "File" then .key |= "AuthorityFile" else . end)' < ${docs}/authority > $AUTHORITY
23+
jq '.components.schemas.RestoreGroup.properties.files.items."$ref" |= "#/components/schemas/AuthorityFile"' < $AUTHORITY > $TMP && mv $TMP $AUTHORITY
24+
rm ${docs}/authority
25+
26+
### File Events
27+
FILE_EVENTS="${docs}/file-events.json"
28+
echo "Transforming File Events docs..."
29+
# prefix v1 summary fields with "v1" and mark as deprecated
30+
jq '.paths |= with_entries( if .key | contains("v1") then .value[].summary |= "v1 - \(.)" else . end)' < ${docs}/file-events > $FILE_EVENTS
31+
jq '.paths |= with_entries( if .key | contains("v1") then .value[].deprecated |= true else . end)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
32+
# prefix v2 summary fields with "v2"
33+
jq '.paths |= with_entries( if .key | contains("v2") then (if .value.post? then .value.post.summary |= "v2 - \(.)" else .value.get.summary |= "v2 - \(.)" end) else . end)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
34+
# order v2 events before v1
35+
jq '.paths |= (to_entries | [_nwise(.; 5)] | reverse | flatten | from_entries)' < $FILE_EVENTS > $TMP && mv $TMP $FILE_EVENTS
36+
rm ${docs}/file-events
37+
38+
### Alert Rules v1
39+
RULES_V1="${docs}/alert-rules"
40+
echo "Transforming Alert Rule v1 docs..."
41+
# prefix summary fields with "v1"
42+
jq '.paths[][].summary |= "v1 - \(.)"' < $RULES_V1 > $TMP && mv $TMP $RULES_V1
43+
# mark v1 endpoints as deprecated
44+
jq '.paths[][].deprecated = true'< $RULES_V1 > $TMP && mv $TMP $RULES_V1
45+
api-spec-converter -f swagger_2 -t openapi_3 -s json -c $RULES_V1 > ${docs}/alert-rules-v1.json
46+
rm "$RULES_V1"
47+
48+
### Alert Rules v2
49+
RULES_V2="${docs}/alert-rules-v2"
50+
echo "Transforming Alert Rule v2 docs..."
51+
# mark rules summary fields with "v2"
52+
jq '.paths[][].summary |= "v2 - \(.)"' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
53+
# hide add-users
54+
jq 'del(.paths."/v2/alert-rules/{id}/users".post)' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
55+
# hide remove-users
56+
jq 'del(.paths."/v2/alert-rules/{id}/remove-users")' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
57+
# hide remove-user-aliases
58+
jq 'del(.paths."/v2/alert-rules/{id}/remove-user-aliases")' < $RULES_V2 > $TMP && mv $TMP $RULES_V2
59+
api-spec-converter -f swagger_2 -t openapi_3 -s json -c $RULES_V2 > ${docs}/alert-rules-v2.json
60+
rm "$RULES_V2"
61+
62+
### Actors
63+
ACTORS="${docs}/actor-enrichment-service"
64+
echo "Transforming Actor docs..."
65+
# rename tags
66+
jq '.paths[][].tags[] |= if . == "actor-api-controller" then "Actors" else . end' < $ACTORS > $TMP && mv $TMP $ACTORS
67+
mv $ACTORS ${docs}/actors.json
11568
}
11669

11770
main "$@"

‎source/api/api-descriptions/user_risk_profile_patch.rmd

-23
This file was deleted.

‎swagger_template.json

+82-30
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,84 @@
11
{
2-
"swagger": "2.0",
3-
"info": {
4-
"title": "Code42 API Documentation",
5-
"version": "v1",
6-
"description": {"$ref": "./user_guides.rmd"}
7-
},
8-
"tags": [
9-
{"name": "Actors", "description": {"$ref": "./api-descriptions/actors.rmd"}},
10-
{"name": "Agents", "description": {"$ref": "./api-descriptions/agents.rmd"}},
11-
{"name": "Alerts and Sessions", "description": {"$ref": "./api-descriptions/sessions.rmd"}},
12-
{"name": "Audit Log", "description": {"$ref": "./api-descriptions/audit_log.rmd"}},
13-
{"name": "Authentication", "description": {"$ref": "./api-descriptions/auth.rmd"}},
14-
{"name": "Cases", "description": {"$ref": "./api-descriptions/cases.rmd"}},
15-
{"name": "Customer", "description": {"$ref": "./api-descriptions/customer.rmd"}},
16-
{"name": "Departments", "description": {"$ref": "./api-descriptions/departments.rmd"}},
17-
{"name": "Devices", "description": {"$ref": "./api-descriptions/device.rmd"}},
18-
{"name": "Directory Groups", "description": {"$ref": "./api-descriptions/directory-groups.rmd"}},
19-
{"name": "File Events", "description": {"$ref": "./api-descriptions/file_events.rmd"}},
20-
{"name": "Legal Hold", "description": {"$ref": "./api-descriptions/legal_hold.rmd"}},
21-
{"name": "Organizations", "description": {"$ref": "./api-descriptions/orgs.rmd"}},
22-
{"name": "Rules", "description": {"$ref": "./api-descriptions/rules.rmd"}},
23-
{"name": "Trusted Activities", "description": {"$ref": "./api-descriptions/trusted_activities.rmd"}},
24-
{"name": "Users", "description": {"$ref": "./api-descriptions/user.rmd"}},
25-
{"name": "Risk Profiles", "description": {"$ref": "./api-descriptions/user_risk_profiles.rmd"}},
26-
{"name": "Watchlists", "description": {"$ref": "./api-descriptions/watchlists.rmd"}}
27-
],
28-
"produces": ["application/json"],
29-
"consumes": ["application/json"],
30-
"paths": {},
31-
"definitions": {}
2+
"openapi": "3.0.0",
3+
"info": {
4+
"description": {"$ref": "./user_guides.rmd"},
5+
"title": "Code42 API Documentation",
6+
"version": "v1"
7+
},
8+
"servers": [],
9+
"paths": {},
10+
"tags": [
11+
{
12+
"description": {"$ref": "./api-descriptions/actors.rmd"},
13+
"name": "Actors"
14+
},
15+
{
16+
"description": {"$ref": "./api-descriptions/agents.rmd"},
17+
"name": "Agents"
18+
},
19+
{
20+
"description": {"$ref": "./api-descriptions/sessions.rmd"},
21+
"name": "Alerts and Sessions"
22+
},
23+
{
24+
"description": {"$ref": "./api-descriptions/audit_log.rmd"},
25+
"name": "Audit Log"
26+
},
27+
{
28+
"description": {"$ref": "./api-descriptions/auth.rmd"},
29+
"name": "Authentication"
30+
},
31+
{
32+
"description": {"$ref": "./api-descriptions/cases.rmd"},
33+
"name": "Cases"
34+
},
35+
{
36+
"description": {"$ref": "./api-descriptions/customer.rmd"},
37+
"name": "Customer"
38+
},
39+
{
40+
"description": {"$ref": "./api-descriptions/departments.rmd"},
41+
"name": "Departments"
42+
},
43+
{
44+
"description": {"$ref": "./api-descriptions/device.rmd"},
45+
"name": "Devices"
46+
},
47+
{
48+
"description": {"$ref": "./api-descriptions/directory-groups.rmd"},
49+
"name": "Directory Groups"
50+
},
51+
{
52+
"description": {"$ref": "./api-descriptions/file_events.rmd"},
53+
"name": "File Events"
54+
},
55+
{
56+
"description": {"$ref": "./api-descriptions/legal_hold.rmd"},
57+
"name": "Legal Hold"
58+
},
59+
{
60+
"description": {"$ref": "./api-descriptions/orgs.rmd"},
61+
"name": "Organizations"
62+
},
63+
{
64+
"description": {"$ref": "./api-descriptions/rules.rmd"},
65+
"name": "Rules"
66+
},
67+
{
68+
"description": {"$ref": "./api-descriptions/trusted_activities.rmd"},
69+
"name": "Trusted Activities"
70+
},
71+
{
72+
"description": {"$ref": "./api-descriptions/user.rmd"},
73+
"name": "Users"
74+
},
75+
{
76+
"description": {"$ref": "./api-descriptions/user_risk_profiles.rmd"},
77+
"name": "Risk Profiles"
78+
},
79+
{
80+
"description": {"$ref": "./api-descriptions/watchlists.rmd"},
81+
"name": "Watchlists"
82+
}
83+
]
3284
}

0 commit comments

Comments
 (0)