Add Euro365 Sportsbook API#2555
Conversation
There was a problem hiding this comment.
Code Review
This pull request introduces the initial OpenAPI 3.0.3 specification for the Euro365 Sportsbook API, covering endpoints for sports, markets, events, odds, scores, settlements, and operational status. The feedback focuses on improving the specification for better client SDK generation and validation. Key recommendations include adding a missing content definition for the /v1/event response, defining explicit schemas instead of relying solely on payload examples (such as for /v1/sports and /rdstn), and modeling comma-separated query parameters as typed arrays with appropriate serialization styles.
| - { name: id, in: query, required: true, schema: { type: string } } | ||
| - { name: sport, in: query, schema: { type: integer } } | ||
| responses: | ||
| "200": { description: Event payload } |
There was a problem hiding this comment.
The 200 response for /v1/event is missing a content definition. Without specifying the media type (e.g., application/json) and a corresponding schema, client generators and documentation tools cannot determine the structure of the returned event payload.
"200":
description: Event payload
content:
application/json:
schema:
type: object| content: | ||
| application/json: | ||
| example: | ||
| success: true | ||
| data: | ||
| - { id: 1, name: Soccer, live_count: 51, prematch_count: 1447 } | ||
| - { id: 2, name: Basketball, live_count: 12, prematch_count: 214 } | ||
| - { id: 5, name: Tennis, live_count: 34, prematch_count: 172 } |
There was a problem hiding this comment.
The response defines an example but lacks a schema definition. In OpenAPI, providing only an example without a schema prevents client SDK generators from creating strongly-typed models for the response data. It is highly recommended to define a structured schema under components/schemas and reference it here using $ref.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
live_count:
type: integer
prematch_count:
type: integer
example:
success: true
data:
- { id: 1, name: Soccer, live_count: 51, prematch_count: 1447 }
- { id: 2, name: Basketball, live_count: 12, prematch_count: 214 }
- { id: 5, name: Tennis, live_count: 34, prematch_count: 172 }| - name: ids | ||
| in: query | ||
| required: true | ||
| schema: { type: string } | ||
| description: "Comma-separated event ids (max 100). Aliases: event_id, fixture_id." |
There was a problem hiding this comment.
Instead of defining the query parameter ids as a raw comma-separated string, it is highly recommended to define it as an array of strings with style: form and explode: false. This allows client generators to produce native array parameters (e.g., List<String> or string[]) and handles serialization/deserialization automatically. Additionally, we can enforce the maxItems: 100 constraint directly in the schema.
- name: ids
in: query
required: true
style: form
explode: false
schema:
type: array
maxItems: 100
items:
type: string
description: "Event IDs (max 100). Aliases: event_id, fixture_id."| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| example: | ||
| - ["ga", ["s5_p18938270", "s5_p18932047"]] |
There was a problem hiding this comment.
The request body for /rdstn has an example but lacks a schema definition. Defining a schema for the Redis-style command array helps validate incoming requests and allows client SDKs to generate appropriate request models.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: array
items:
oneOf:
- type: string
- type: array
items:
type: string
example:
- ["ga", ["s5_p18938270", "s5_p18932047"]]
Adds the Euro365 Sportsbook API to the directory.