Skip to content

Commit 5d05882

Browse files
creed-brattoncreed-bratton
authored
feat: add OpenAPI spec and Swagger UI preview (#60)
Closes #33.
1 parent 88435af commit 5d05882

2 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ A RESTful API for validating [publiccode.yml](https://github.com/italia/publicco
77
files, using the [publiccode-parser-go](https://github.com/italia/publiccode-parser-go)
88
library.
99

10+
## API reference
11+
12+
The OpenAPI spec is in [`publiccode-validator-api.oas.yaml`](publiccode-validator-api.oas.yaml).
13+
14+
[Browse the interactive Swagger UI preview](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/italia/publiccode-validator-api/main/publiccode-validator-api.oas.yaml)
15+
1016
## Usage
1117

1218
```console

‎publiccode-validator-api.oas.yaml‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
openapi: 3.1.0
2+
info:
3+
title: publiccode-validator-api
4+
version: dev
5+
description: >
6+
REST API to validate and normalize publiccode.yml files
7+
against the official standard.
8+
9+
10+
The `/validate` endpoint accepts both `POST` and the `QUERY`
11+
HTTP method (RFC 9110) with a publiccode.yml body and returns
12+
validation results plus a normalized version of the file.
13+
license:
14+
name: AGPL-3.0
15+
identifier: AGPL-3.0-only
16+
contact:
17+
url: "https://github.com/italia/publiccode-validator-api"
18+
19+
servers:
20+
- url: /v1
21+
22+
paths:
23+
/status:
24+
get:
25+
operationId: getStatus
26+
summary: Get API status
27+
tags: [status]
28+
responses:
29+
"200":
30+
description: OK
31+
headers:
32+
Cache-Control:
33+
schema:
34+
type: string
35+
example: no-cache
36+
content:
37+
application/json:
38+
schema:
39+
$ref: "#/components/schemas/Status"
40+
example:
41+
v: "1.0.0"
42+
commit: "abc1234"
43+
44+
/validate:
45+
post:
46+
operationId: validatePubliccode
47+
summary: Validate a publiccode.yml file
48+
description: >
49+
Parses and validates the publiccode.yml file in the request body.
50+
Returns whether the file is valid, a list of validation issues,
51+
and a normalized version of the file if valid.
52+
53+
54+
The same endpoint also accepts the `QUERY` HTTP method.
55+
tags: [validation]
56+
parameters:
57+
- name: external-checks
58+
in: query
59+
required: false
60+
description: >
61+
Enable external checks such as URL reachability.
62+
Disabled by default for performance.
63+
schema:
64+
type: boolean
65+
default: false
66+
requestBody:
67+
required: true
68+
content:
69+
application/yaml:
70+
schema:
71+
type: string
72+
example: |
73+
publiccodeYmlVersion: "0.3"
74+
name: My Software
75+
url: "https://example.com/repo"
76+
responses:
77+
"200":
78+
description: Validation result (regardless of whether the file is valid)
79+
content:
80+
application/json:
81+
schema:
82+
$ref: "#/components/schemas/ValidationResponse"
83+
examples:
84+
valid:
85+
summary: Valid file
86+
value:
87+
valid: true
88+
results: []
89+
normalized: "publiccodeYmlVersion: \"0.3\"\nname: My Software\n"
90+
invalid:
91+
summary: Invalid file
92+
value:
93+
valid: false
94+
results:
95+
- key: publiccodeYmlVersion
96+
description: "missing required field"
97+
normalized: null
98+
"400":
99+
description: Bad request (e.g. empty body)
100+
content:
101+
application/problem+json:
102+
schema:
103+
$ref: "#/components/schemas/ProblemJSON"
104+
example:
105+
title: empty body
106+
detail: need a body to validate
107+
status: 400
108+
"404":
109+
description: Not found
110+
content:
111+
application/problem+json:
112+
schema:
113+
$ref: "#/components/schemas/ProblemJSON"
114+
example:
115+
title: Not Found
116+
detail: Not Found
117+
status: 404
118+
119+
components:
120+
schemas:
121+
Status:
122+
type: object
123+
required: [v, commit]
124+
properties:
125+
v:
126+
type: string
127+
description: API version
128+
example: "1.0.0"
129+
commit:
130+
type: string
131+
description: Git commit hash
132+
example: "abc1234"
133+
134+
ValidationResponse:
135+
type: object
136+
required: [valid, results]
137+
properties:
138+
valid:
139+
type: boolean
140+
description: Whether the file passed validation with no errors
141+
results:
142+
type: array
143+
description: List of validation issues (warnings and errors)
144+
items:
145+
type: object
146+
description: A validation issue
147+
additionalProperties: true
148+
normalized:
149+
description: >
150+
Normalized publiccode.yml content, present only when
151+
the file is valid.
152+
oneOf:
153+
- type: string
154+
- type: "null"
155+
156+
ProblemJSON:
157+
description: Error response following RFC 9457 (Problem Details for HTTP APIs)
158+
type: object
159+
required: [title, status]
160+
properties:
161+
code:
162+
type: string
163+
description: Machine-readable error code
164+
title:
165+
type: string
166+
description: Short human-readable summary
167+
detail:
168+
type: string
169+
description: Human-readable explanation
170+
status:
171+
type: integer
172+
description: HTTP status code

0 commit comments

Comments
 (0)