Skip to content

Commit 824a74a

Browse files
vpeterssonvpetersson
committed
Work in progress: overhaul and synchronize API docs with workflow docs
Signed-off-by: Viktor Petersson <[email protected]>
1 parent 58d9120 commit 824a74a

File tree

3 files changed

+131
-25
lines changed

3 files changed

+131
-25
lines changed

‎api-flow/publisher.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ sequenceDiagram
88
participant Vendor
99
participant TEA_API
1010
participant TEA_Index
11-
participant Product_Repository
11+
participant TEA Product Index
1212
participant SBOM_Generator
1313
participant VEX_Generator
1414
participant VDR_Generator
1515
participant Consumer
1616
17-
Vendor->>Product_Repository: Create new product version
18-
Product_Repository-->>Vendor: Product version created
17+
Vendor ->> TEA Product Index: POST to /v1/product-index to create new product
18+
TEA Product Index -->> Vendor: Product version created and Tea Product Identifier returned
1919
2020
Vendor->>TEA_API: POST /collection (Create new collection with FIRST_MENTION lifecycle event)
2121
TEA_API->>TEA_Index: Update index with new collection

‎spec/README.md

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,23 @@ The OpenAPI 3.1 specification for the Transparency Exchange API is available in
88

99
We use the OpenAPI Generator with configuration per language/framework in the `generators` folder. An example is:
1010

11+
```bash
12+
docker run \
13+
--rm \
14+
-v "$(PWD):/local" \
15+
openapitools/openapi-generator-cli \
16+
batch --clean /local/spec/generators/typescript.yaml
1117
```
12-
docker run --rm -v "$(PWD):/local" openapitools/openapi-generator-cli batch --clean /local/spec/generators/typescript.yaml
13-
```
18+
19+
## Preview Specs
20+
21+
Fire up the `swagger-ui` with Docker from the root of the repository:
22+
23+
```bash
24+
docker run \
25+
-p 8080:8080 \
26+
-e SWAGGER_JSON=/koala/spec/openapi.json \
27+
-v $(pwd):/koala swaggerapi/swagger-ui
28+
```
29+
30+
And browse to [http://localhost:8080](http://localhost:8080).

‎spec/openapi.json

Lines changed: 109 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
"paths": {
2626
"/product-index/{product-identifier}": {
2727
"get": {
28-
"description": "Access the TEA Index for the supplied product identifier",
28+
"description": "Returns the corresponding leafs for a given TEA Product Identifier",
2929
"operationId": "getTeaIndex",
3030
"parameters": [
3131
{
@@ -40,7 +40,7 @@
4040
],
4141
"responses": {
4242
"200": {
43-
"description": "Requested TEA Index found and returned",
43+
"description": "Requested Product TEA Index found and returned",
4444
"content": {
4545
"application/json": {
4646
"schema": {
@@ -64,19 +64,112 @@
6464
]
6565
}
6666
]
67-
67+
6868
}
6969
}
7070
}
7171
},
72-
72+
7373
"404": {
7474
"$ref": "#/components/responses/404-object-by-id-not-found"
7575
}
76-
76+
7777
},
7878
"tags": [
79-
"TEA Index"
79+
"TEA Product Index"
80+
]
81+
},
82+
"patch": {
83+
"description": "Update an existing TEA Product Index entry",
84+
"operationId": "updateTeaIndex",
85+
"parameters": [
86+
{
87+
"$ref": "#/components/parameters/product-identifier"
88+
}
89+
],
90+
"requestBody": {
91+
"required": true,
92+
"content": {
93+
"application/json": {
94+
"schema": {
95+
"type": "object",
96+
"properties": {
97+
"product-name": {
98+
"type": "string"
99+
}
100+
},
101+
"required": [
102+
"product-name"
103+
]
104+
}
105+
}
106+
}
107+
},
108+
"responses": {
109+
"200": {
110+
"description": "TEA Index entry updated successfully",
111+
"content": {
112+
"application/json": {
113+
"schema": {
114+
"$ref": "#/components/schemas/tea-product-index"
115+
}
116+
}
117+
}
118+
},
119+
"400": {
120+
"description": "Invalid request body",
121+
"content": {
122+
"application/json": {}
123+
}
124+
},
125+
"404": {
126+
"$ref": "#/components/responses/404-object-by-id-not-found"
127+
}
128+
},
129+
"tags": [
130+
"TEA Product Index"
131+
]
132+
}
133+
},
134+
"/product-index": {
135+
"post": {
136+
"description": "Create TEA Product Index entry for the supplied product identifier",
137+
"operationId": "createTeaIndex",
138+
"parameters": [
139+
{
140+
"$ref": "#/components/parameters/product-identifier"
141+
}
142+
],
143+
"requestBody": {
144+
"required": true,
145+
"content": {
146+
"application/json": {
147+
"schema": {
148+
"$ref": "#/components/schemas/tea-product-index"
149+
}
150+
}
151+
}
152+
},
153+
"responses": {
154+
"201": {
155+
"description": "TEA Index entry created successfully",
156+
"content": {
157+
"application/json": {
158+
"schema": {
159+
"$ref": "#/components/schemas/tea-product-index"
160+
}
161+
}
162+
}
163+
},
164+
"400": {
165+
"description": "Invalid request body",
166+
"content": {
167+
"application/json": {}
168+
}
169+
}
170+
},
171+
"tags": [
172+
"TEA Product Index"
80173
]
81174
}
82175
},
@@ -150,15 +243,11 @@
150243
},
151244
"product-name": {
152245
"type": "string"
153-
},
154-
"product-version": {
155-
"type": "string"
156246
}
157247
},
158-
"reqiured": [
248+
"required": [
159249
"uuid",
160-
"product-name",
161-
"product-version"
250+
"product-name"
162251
]
163252
},
164253
"tea-leaf": {
@@ -177,19 +266,19 @@
177266
"type": "string",
178267
"format": "date-time"
179268
},
180-
"prerelease": {
269+
"pre-release": {
181270
"type": "boolean"
182271
},
183272
"tea-collection-uuid": {
184273
"$ref": "#/components/schemas/type-uuid"
185274
}
186275
},
187-
"reqiured": [
276+
"required": [
188277
"uuid",
189278
"product-name",
190279
"product-version",
191280
"release-date",
192-
"prerelease",
281+
"pre-release",
193282
"tea-collection-uuid"
194283
]
195284
},
@@ -223,7 +312,7 @@
223312
"minItems": 1
224313
}
225314
},
226-
"reqiured": [
315+
"required": [
227316
"uuid",
228317
"product-name",
229318
"product-version",
@@ -255,7 +344,7 @@
255344
"minItems": 1
256345
}
257346
},
258-
"reqiured": [
347+
"required": [
259348
"uuid",
260349
"name",
261350
"type",
@@ -291,13 +380,13 @@
291380
"format": "uri"
292381
}
293382
},
294-
"reqiured": [
383+
"required": [
295384
"uuid",
296385
"description",
297386
"mime_type",
298387
"artifact_url",
299388
"artifact_size_in_bytes",
300-
"artifact_checksum"
389+
"artifact_checksum"
301390
]
302391
},
303392
"type-author": {
@@ -531,7 +620,7 @@
531620
"security": [],
532621
"tags": [
533622
"TEA Collection",
534-
"TEA Index",
623+
"TEA Product Index",
535624
"TEA Leaf"
536625
],
537626
"externalDocs": {

0 commit comments

Comments
 (0)