Kong / Kong/docs.konghq.com

List all services on the Kong Admin API spec claims to return a single service

Open
#8,239 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.