List all services on the Kong Admin API spec claims to return a single service
- Dominant language
- Ruby
- Stars
- 212
- Forks
- 587
- PR merge metrics
- No merged PRs in 30d
Description
### Where is the problem?
https://docs.konghq.com/gateway/api/admin-oss/latest/#/Services/list-service
### What happened?
The OpenAPI spec for the (list services endpoint)[https://docs.konghq.com/gateway/api/admin-oss/latest/#/Services/list-service] claims that the endpoint returns a single `Service` instance when in fact returns a list of services.
The root cause is defined on the [spec itself](../blob/master/api-specs/Gateway-OSS/3.9/kong-oss.yaml#L5224)
```yaml
/services:
get:
description: List all services
operationId: list-service
parameters:
- $ref: '#/components/parameters/pagination-size'
- $ref: '#/components/parameters/pagination-offset'
- $ref: '#/components/parameters/pagination-tags-filter'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
application/xml:
schema:
type: object
properties: {}
description: A successful response listing services
'401':
$ref: '#/components/responses/HTTP401Error'
summary: List all services
tags:
- Services
```
### What did you expect to happen?
The spec should indicate that the endpoint return a list of services. Something along these lines:
```yaml
/services:
get:
description: List all services
operationId: list-service
parameters:
- $ref: '#/components/parameters/pagination-size'
- $ref: '#/components/parameters/pagination-offset'
- $ref: '#/components/parameters/pagination-tags-filter'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/Service'
type: array
offset:
$ref: '#/components/schemas/pagination-offset-response'
application/xml:
schema:
type: object
properties: {}
description: A successful response listing services
'401':
$ref: '#/components/responses/HTTP401Error'
summary: List all services
tags:
- Services
```
### Code of Conduct and Community Expectations
- [X] I agree to follow this project's Code of Conduct
- [X] I agree to abide by the Community Expectations
Contributor guide
No contributing guide indexed for this repository
Research direction
Open api-specs/Gateway-OSS/3.9/kong-oss.yaml around line 5224 and inspect the GET response for /services. Compare its schema with the endpoint's documented list behavior and the example in this issue. Done means the OpenAPI response describes the returned service collection and pagination fields accurately.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100