Skip to content

Commit 3ad22fa

Browse files
timotejblazictimotejblazic
committed
swagger api documentation
1 parent 0b5224e commit 3ad22fa

3 files changed

Lines changed: 244 additions & 0 deletions

File tree

‎docs/openapi.yaml‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
openapi: 3.0.3
2+
info:
3+
title: CloudShopt Payment Service API
4+
version: 1.0.0
5+
tags:
6+
- name: Health
7+
- name: Diagnostics
8+
- name: Checkout
9+
- name: Webhooks
10+
11+
paths:
12+
/healthz:
13+
get:
14+
tags: [Health]
15+
summary: Health check
16+
responses:
17+
"200":
18+
description: OK
19+
content:
20+
application/json:
21+
schema:
22+
$ref: "#/components/schemas/StatusOkBool"
23+
24+
/info:
25+
get:
26+
tags: [Diagnostics]
27+
summary: Service info (sha, time)
28+
responses:
29+
"200":
30+
description: Info
31+
content:
32+
application/json:
33+
schema:
34+
$ref: "#/components/schemas/InfoResponse"
35+
36+
/database:
37+
get:
38+
tags: [Diagnostics]
39+
summary: Database connectivity check (optional)
40+
responses:
41+
"200":
42+
description: DB OK (or not used)
43+
content:
44+
application/json:
45+
schema:
46+
$ref: "#/components/schemas/DatabaseOkResponse"
47+
"500":
48+
description: DB connection failed
49+
content:
50+
application/json:
51+
schema:
52+
$ref: "#/components/schemas/DatabaseFailResponse"
53+
54+
/checkout-session:
55+
post:
56+
tags: [Checkout]
57+
summary: Create Stripe Checkout Session (JWT)
58+
description: Returns Stripe hosted checkout URL. Amount is derived from order total (cents).
59+
security:
60+
- bearerAuth: []
61+
requestBody:
62+
required: true
63+
content:
64+
application/json:
65+
schema:
66+
$ref: "#/components/schemas/CreateCheckoutSessionRequest"
67+
responses:
68+
"200":
69+
description: Session created
70+
content:
71+
application/json:
72+
schema:
73+
$ref: "#/components/schemas/CreateCheckoutSessionResponse"
74+
"401":
75+
$ref: "#/components/responses/Unauthorized"
76+
"404":
77+
$ref: "#/components/responses/NotFound"
78+
"422":
79+
$ref: "#/components/responses/ValidationError"
80+
81+
/webhooks/stripe:
82+
post:
83+
tags: [Webhooks]
84+
summary: Stripe webhook receiver
85+
description: Stripe calls this endpoint. Signature is verified using STRIPE_WEBHOOK_SECRET.
86+
requestBody:
87+
required: true
88+
content:
89+
application/json:
90+
schema:
91+
type: object
92+
responses:
93+
"200":
94+
description: Received
95+
content:
96+
application/json:
97+
schema:
98+
$ref: "#/components/schemas/WebhookReceived"
99+
"400":
100+
description: Invalid signature / bad request
101+
content:
102+
application/json:
103+
schema:
104+
$ref: "#/components/schemas/ErrorMessage"
105+
106+
components:
107+
securitySchemes:
108+
bearerAuth:
109+
type: http
110+
scheme: bearer
111+
bearerFormat: JWT
112+
113+
responses:
114+
Unauthorized:
115+
description: Unauthorized
116+
content:
117+
application/json:
118+
schema:
119+
$ref: "#/components/schemas/ErrorMessage"
120+
121+
NotFound:
122+
description: Not found
123+
content:
124+
application/json:
125+
schema:
126+
$ref: "#/components/schemas/ErrorMessage"
127+
128+
ValidationError:
129+
description: Validation error
130+
content:
131+
application/json:
132+
schema:
133+
$ref: "#/components/schemas/ValidationError"
134+
135+
schemas:
136+
ErrorMessage:
137+
type: object
138+
required: [message]
139+
properties:
140+
message: { type: string }
141+
142+
ValidationError:
143+
type: object
144+
required: [message, errors]
145+
properties:
146+
message: { type: string }
147+
errors:
148+
type: object
149+
additionalProperties:
150+
type: array
151+
items: { type: string }
152+
153+
StatusOkBool:
154+
type: object
155+
required: [ok]
156+
properties:
157+
ok: { type: boolean, example: true }
158+
159+
InfoResponse:
160+
type: object
161+
required: [ok, service, sha, time]
162+
properties:
163+
ok: { type: boolean, example: true }
164+
service: { type: string, example: payment-service }
165+
sha: { type: string, nullable: true, example: 0.0.1 }
166+
time: { type: string, format: date-time, example: "2026-01-29T10:15:30.123Z" }
167+
168+
DatabaseOkResponse:
169+
type: object
170+
required: [ok, db, time]
171+
properties:
172+
ok: { type: boolean, example: true }
173+
db:
174+
type: object
175+
required: [connection, database, ping_ms]
176+
properties:
177+
connection: { type: string, example: mysql }
178+
database: { type: string, example: cloudshopt_payments_dev }
179+
ping_ms: { type: number, format: float, example: 1.25 }
180+
time: { type: string, format: date-time, example: "2026-01-29T10:15:30.123Z" }
181+
182+
DatabaseFailResponse:
183+
type: object
184+
required: [ok, error, message]
185+
properties:
186+
ok: { type: boolean, example: false }
187+
error: { type: string, example: DB connection failed }
188+
message: { type: string, nullable: true, example: "SQLSTATE[HY000] ..." }
189+
190+
CreateCheckoutSessionRequest:
191+
type: object
192+
required: [order_id]
193+
properties:
194+
order_id: { type: integer, minimum: 1, example: 10 }
195+
196+
CreateCheckoutSessionResponse:
197+
type: object
198+
required: [url, session_id]
199+
properties:
200+
url: { type: string, example: https://checkout.stripe.com/c/pay/cs_test_... }
201+
session_id: { type: string, example: cs_test_a11lqwy13iFvK69o... }
202+
203+
WebhookReceived:
204+
type: object
205+
required: [received]
206+
properties:
207+
received: { type: boolean, example: true }

‎resources/views/swagger.blade.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
<title>API Docs</title>
7+
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
8+
</head>
9+
<body>
10+
<div id="swagger-ui"></div>
11+
12+
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
13+
<script>
14+
window.onload = () => {
15+
SwaggerUIBundle({
16+
url: "/api/payments/openapi.yaml",
17+
dom_id: "#swagger-ui",
18+
});
19+
};
20+
</script>
21+
</body>
22+
</html>

‎routes/api.php‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,21 @@
55
use Illuminate\Support\Facades\DB;
66
use Illuminate\Support\Facades\Route;
77

8+
Route::get('/openapi.yaml', function () {
9+
$path = base_path('docs/openapi.yaml');
10+
11+
abort_unless(file_exists($path), 404, 'openapi.yaml not found');
12+
13+
return response()->file($path, [
14+
'Content-Type' => 'application/yaml; charset=utf-8',
15+
'Cache-Control' => 'no-store',
16+
]);
17+
});
18+
19+
Route::get('/docs', function () {
20+
return response()->view('swagger');
21+
});
22+
823
Route::get('/info', function () {
924
return response()->json([
1025
'ok11' => true,

0 commit comments

Comments
 (0)