Skip to content

Commit bcb2367

Browse files
nscuronscuro
committed
Add api module
Signed-off-by: nscuro <nscuro@protonmail.com>
1 parent fa1fd5b commit bcb2367

17 files changed

Lines changed: 1400 additions & 2 deletions

File tree

‎.github/workflows/ci-openapi.yaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# This file is part of Dependency-Track.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#
15+
# SPDX-License-Identifier: Apache-2.0
16+
# Copyright (c) OWASP Foundation. All Rights Reserved.
17+
name: OpenAPI
18+
19+
on:
20+
pull_request:
21+
branches:
22+
- main
23+
- "feature-**"
24+
25+
concurrency:
26+
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
27+
cancel-in-progress: true
28+
29+
permissions: { }
30+
31+
jobs:
32+
lint:
33+
name: Lint
34+
runs-on: ubuntu-latest
35+
permissions:
36+
checks: write
37+
timeout-minutes: 5
38+
steps:
39+
- name: Checkout Repository
40+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
41+
- name: Lint OpenAPI Spec
42+
uses: stoplightio/spectral-action@577bade2d6e0eeb50528c94182a5588bf961ae8f # tag=v0.8.12
43+
with:
44+
spectral_ruleset: "api/.spectral/ruleset.yaml"
45+
file_glob: "api/openapi.yaml"
46+
47+
# TODO: Uncomment after the OpenAPI Spec is present in main.
48+
# breaking-changes:
49+
# name: Breaking Changes
50+
# runs-on: ubuntu-latest
51+
# timeout-minutes: 5
52+
# steps:
53+
# - name: Checkout Repository
54+
# uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
55+
# with:
56+
# fetch-depth: 0
57+
# - name: Prepare OpenAPI Spec Comparison
58+
# run: |-
59+
# cd api/src/main/resources/org/dependencytrack/api/v2
60+
# mv openapi.yaml openapi-after.yaml
61+
#
62+
# git checkout ${{ github.event.pull_request.base.sha }} -- openapi.yaml
63+
# mv openapi.yaml openapi-before.yaml
64+
# - name: Detect Breaking Changes in OpenAPI Spec
65+
# run: |-
66+
# docker run -i --rm \
67+
# -v "$(pwd)/api/src/main/resources/org/dependencytrack/api/v2:/work:ro" \
68+
# pb33f/openapi-changes summary --no-color --no-logo \
69+
# openapi-before.yaml openapi-after.yaml

‎.mvn/maven-build-cache-config.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
</configuration>
3232
<input>
3333
<global>
34-
<glob>{*.java,*.properties,*.proto,*.sql,*.xml}</glob>
34+
<glob>{*.java,*.properties,*.proto,*.sql,*.xml,*.yaml}</glob>
3535
<includes>
3636
<include>src/</include>
3737
</includes>

‎api/.spectral/ruleset.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# This file is part of Dependency-Track.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#
15+
# SPDX-License-Identifier: Apache-2.0
16+
# Copyright (c) OWASP Foundation. All Rights Reserved.
17+
extends:
18+
- ["spectral:oas", "all"]
19+
- ["./zalando.yaml", "all"]
20+
formats:
21+
- "oas3"

‎api/.spectral/zalando.yaml‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# This file is part of Dependency-Track.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#
15+
# SPDX-License-Identifier: Apache-2.0
16+
# Copyright (c) OWASP Foundation. All Rights Reserved.
17+
18+
# Rules to assert conformance to a curated subset of Zalando's
19+
# RESTful API guidelines: https://opensource.zalando.com/restful-api-guidelines/#
20+
#
21+
# Credit to the folks at baloise for providing these spectral rules:
22+
# https://github.com/baloise-incubator/spectral-ruleset/blob/main/zalando.yml
23+
rules:
24+
must-use-semantic-versioning:
25+
message: '{{error}}'
26+
description: MUST use semantic versioning [116]
27+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#116
28+
severity: error
29+
given: $.info.version
30+
then:
31+
function: schema
32+
functionOptions:
33+
schema:
34+
type: string
35+
pattern: '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$'
36+
37+
must-use-snake-case-for-property-names:
38+
message: Property name has to be ASCII snake_case
39+
description: MUST property names must be ASCII snake_case [118]
40+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#118
41+
severity: error
42+
given: $.paths.*.*[responses,requestBody]..content..schema..properties.*~
43+
then:
44+
function: pattern
45+
functionOptions:
46+
match: ^[a-z_][a-z_0-9]*$
47+
48+
must-use-lowercase-with-hypens-for-path-segements:
49+
message: Path segments have to be lowercase separate words with hyphens
50+
description: MUST use lowercase separate words with hyphens for path segments [129]
51+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#129
52+
severity: error
53+
given: $.paths.*~
54+
then:
55+
function: pattern
56+
functionOptions:
57+
match: ^(?=((([\/a-z][a-z0-9\-\/]*)?({[^}]*})?)+))\1$
58+
59+
must-use-snake-case-for-query-parameters:
60+
message: Query parameters must be snake_case
61+
description: MUST use snake_case (never camelCase) for query parameters [130]
62+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#130
63+
severity: error
64+
given: $.paths.*.*.parameters[?(@ && @.in=='query')].name
65+
then:
66+
function: pattern
67+
functionOptions:
68+
match: ^[a-z][_a-z0-9]*$
69+
70+
must-use-normalized-paths-without-empty-path-segments:
71+
message: Empty path segments are not allowed
72+
description: MUST use normalized paths without empty path segments and trailing slashes [136]
73+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#136
74+
severity: error
75+
given: $.paths.*~
76+
then:
77+
function: pattern
78+
functionOptions:
79+
notMatch: //
80+
81+
must-use-normalized-paths-without-trailing-slash:
82+
message: Path with trailing slash is not allowed
83+
description: MUST use normalized paths without empty path segments and trailing slashes [136]
84+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#136
85+
severity: error
86+
given: $.paths.*~
87+
then:
88+
function: pattern
89+
functionOptions:
90+
notMatch: /$
91+
92+
must-specify-default-response:
93+
message: Operation does not contain a default response
94+
description: MUST specify success and error responses [151]
95+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#151
96+
severity: error
97+
given: $.paths.*.*.responses
98+
then:
99+
field: default
100+
function: truthy
101+
102+
must-use-standard-formats-for-date-and-time-properties-example:
103+
message: "You should provide an example for {{property}}"
104+
description: MUST use standard formats for date and time properties [169]
105+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#169
106+
severity: warn # Not an error as you only should provide an example to help your consumers
107+
given: $.paths..[?(@.type === 'string' && (@.format === 'date-time' || @.format === 'date' || @.format === 'time' || @.format === 'duration' || @.format === 'period'))]
108+
then:
109+
field: example
110+
function: truthy
111+
112+
must-use-standard-formats-for-date-and-time-properties-utc:
113+
message: "You should UTC for {{property}}"
114+
description: MUST use standard formats for date and time properties [169]
115+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#169
116+
severity: warn # Not an error as you only should provide an example to help your consumers
117+
given: $.paths..[?(@.type === 'string' && @.format === 'date-time')]
118+
then:
119+
field: example
120+
function: pattern
121+
functionOptions:
122+
match: "Z$"
123+
124+
must-use-problem-json-as-default-response:
125+
message: Operation must use problem json as default response
126+
description: MUST specify success and error responses [151]
127+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#151
128+
severity: error
129+
given: $.paths.*.*.responses.default
130+
then:
131+
field: content.application/problem+json
132+
function: truthy
133+
134+
must-define-a-format-for-number-types:
135+
message: Numeric properties must have valid format specified
136+
description: MUST define a format for number and integer types [171]
137+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#171
138+
severity: error
139+
given: $.paths.*.*..schema..properties..[?(@ && @.type=='number')]
140+
then:
141+
- field: format
142+
function: defined
143+
- field: format
144+
function: pattern
145+
functionOptions:
146+
match: ^(float|double|decimal)$
147+
148+
must-define-a-format-for-integer-types:
149+
message: Numeric properties must have valid format specified
150+
description: MUST define a format for number and integer types [171]
151+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#171
152+
severity: error
153+
given: $.paths.*.*..schema..properties..[?(@ && @.type=='integer')]
154+
then:
155+
- field: format
156+
function: defined
157+
- field: format
158+
function: pattern
159+
functionOptions:
160+
match: ^(int32|int64|bigint)$
161+
162+
should-prefer-standard-media-type-names:
163+
message: Custom media types should only be used for versioning
164+
description: SHOULD prefer standard media type name application/json [172]
165+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#172
166+
severity: warn
167+
given: $.paths.*.*.responses.*.content.*~
168+
then:
169+
function: pattern
170+
functionOptions:
171+
match: ^application\/(problem\+)?json$|^[a-zA-Z0-9_]+\/[-+.a-zA-Z0-9_]+;(v|version)=[0-9]+$
172+
173+
must-use-problem-json-for-errors:
174+
message: Error response must be application/problem+json
175+
description: MUST support problem JSON [176]
176+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#176
177+
severity: error
178+
given: $.paths.*.*.responses[?(@ && @property.match(/^(4|5)/))]
179+
then:
180+
field: content.application/problem+json
181+
function: truthy
182+
183+
should-declare-enum-values-using-upper-snake-case-format:
184+
message: 'Enum values should be in UPPER_SNAKE_CASE format'
185+
description: SHOULD declare enum values using UPPER_SNAKE_CASE format [240]
186+
documentationUrl: https://opensource.zalando.com/restful-api-guidelines/#240
187+
severity: warn
188+
given: $.paths..[?(@ && @.type=='string')].[enum,x-extensible-enum].*
189+
then:
190+
function: pattern
191+
functionOptions:
192+
match: ^[A-Z][A-Z_0-9]*$

‎api/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# api
2+
3+
Definition of Dependency-Track's REST API, in [OpenAPI v3.0] format.
4+
5+
The API draws inspiration from [Zalando's RESTful API Guidelines].
6+
7+
Conformance to API guidelines is enforced with [spectral].
8+
9+
Interfaces and model classes are generated as part of the build using [openapi-generator].
10+
11+
[OpenAPI v3.0]: https://spec.openapis.org/oas/v3.0.3.html
12+
[Zalando's RESTful API Guidelines]: https://opensource.zalando.com/restful-api-guidelines/
13+
[openapi-generator]: https://github.com/OpenAPITools/openapi-generator
14+
[spectral]: https://github.com/stoplightio/spectral

0 commit comments

Comments
 (0)