Skip to content

Commit c07a3d9

Browse files
PRAteek-singHWYPRAteek-singHWY
authored
Add initial OpenAPI (Swagger) specification for OpenCRE REST API (#708)
* docs(api): add initial OpenAPI specification * docs(api): add initial OpenAPI specification
1 parent f89af81 commit c07a3d9

File tree

1 file changed

+229
-0
lines changed

1 file changed

+229
-0
lines changed

‎docs/api/openapi.yaml‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
openapi: 3.0.1
2+
3+
info:
4+
title: OpenCRE REST API
5+
description: >
6+
Public REST API for OpenCRE (Open Common Requirement Enumeration).
7+
This specification documents the currently exposed, read-only API
8+
endpoints implemented by the OpenCRE backend.
9+
version: 1.0.0
10+
11+
paths:
12+
/rest/v1/id/{creid}:
13+
get:
14+
summary: Get a CRE by ID
15+
description: Retrieve a Common Requirement Enumeration (CRE) by its external ID.
16+
parameters:
17+
- name: creid
18+
in: path
19+
required: true
20+
description: External CRE identifier
21+
schema:
22+
type: string
23+
- name: format
24+
in: query
25+
required: false
26+
description: Optional response format
27+
schema:
28+
type: string
29+
enum: [json, md, csv, oscal]
30+
- name: include_only
31+
in: query
32+
required: false
33+
description: Filter returned fields
34+
schema:
35+
type: array
36+
items:
37+
type: string
38+
responses:
39+
'200':
40+
description: CRE found
41+
content:
42+
application/json:
43+
schema:
44+
type: object
45+
properties:
46+
data:
47+
type: object
48+
'404':
49+
description: CRE not found
50+
51+
/rest/v1/name/{crename}:
52+
get:
53+
summary: Get a CRE by name
54+
description: Retrieve a Common Requirement Enumeration (CRE) by its name.
55+
parameters:
56+
- name: crename
57+
in: path
58+
required: true
59+
description: CRE name
60+
schema:
61+
type: string
62+
- name: format
63+
in: query
64+
required: false
65+
schema:
66+
type: string
67+
enum: [json, md, csv, oscal]
68+
responses:
69+
'200':
70+
description: CRE found
71+
content:
72+
application/json:
73+
schema:
74+
type: object
75+
'404':
76+
description: CRE not found
77+
78+
/rest/v1/{ntype}/{name}:
79+
get:
80+
summary: Get nodes by type and name
81+
description: >
82+
Retrieve standards, tools, or other node types by name.
83+
Supports pagination and filtering.
84+
parameters:
85+
- name: ntype
86+
in: path
87+
required: true
88+
description: Node type (e.g. standard)
89+
schema:
90+
type: string
91+
- name: name
92+
in: path
93+
required: true
94+
description: Node name
95+
schema:
96+
type: string
97+
- name: section
98+
in: query
99+
required: false
100+
schema:
101+
type: string
102+
- name: subsection
103+
in: query
104+
required: false
105+
schema:
106+
type: string
107+
- name: sectionID
108+
in: query
109+
required: false
110+
schema:
111+
type: string
112+
- name: page
113+
in: query
114+
required: false
115+
schema:
116+
type: integer
117+
- name: items_per_page
118+
in: query
119+
required: false
120+
schema:
121+
type: integer
122+
- name: format
123+
in: query
124+
required: false
125+
schema:
126+
type: string
127+
enum: [json, md, csv, oscal]
128+
responses:
129+
'200':
130+
description: Nodes retrieved
131+
content:
132+
application/json:
133+
schema:
134+
type: object
135+
'404':
136+
description: Node not found
137+
138+
/rest/v1/tags:
139+
get:
140+
summary: Get documents by tag
141+
description: Retrieve documents associated with one or more tags.
142+
parameters:
143+
- name: tag
144+
in: query
145+
required: true
146+
description: Tag name(s)
147+
schema:
148+
type: array
149+
items:
150+
type: string
151+
- name: format
152+
in: query
153+
required: false
154+
schema:
155+
type: string
156+
enum: [json, md, csv, oscal]
157+
responses:
158+
'200':
159+
description: Documents retrieved
160+
content:
161+
application/json:
162+
schema:
163+
type: object
164+
'404':
165+
description: Tag not found
166+
167+
/rest/v1/root_cres:
168+
get:
169+
summary: Get root CREs
170+
description: Retrieve top-level CREs for browsing.
171+
parameters:
172+
- name: format
173+
in: query
174+
required: false
175+
schema:
176+
type: string
177+
enum: [json, md, csv, oscal]
178+
responses:
179+
'200':
180+
description: Root CREs retrieved
181+
content:
182+
application/json:
183+
schema:
184+
type: object
185+
'404':
186+
description: No root CREs found
187+
188+
/rest/v1/standards:
189+
get:
190+
summary: List standards
191+
description: Retrieve all known standards.
192+
responses:
193+
'200':
194+
description: Standards retrieved
195+
content:
196+
application/json:
197+
schema:
198+
type: array
199+
items:
200+
type: string
201+
202+
/rest/v1/text_search:
203+
get:
204+
summary: Text search
205+
description: Perform a free-text search across CREs and standards.
206+
parameters:
207+
- name: text
208+
in: query
209+
required: true
210+
description: Search query
211+
schema:
212+
type: string
213+
- name: format
214+
in: query
215+
required: false
216+
schema:
217+
type: string
218+
enum: [json, md, csv, oscal]
219+
responses:
220+
'200':
221+
description: Search results
222+
content:
223+
application/json:
224+
schema:
225+
type: array
226+
items:
227+
type: object
228+
'404':
229+
description: No results found

0 commit comments

Comments
 (0)