Documentation: Admin API Swagger Docs


#1

Hello

I made this post on the github issues before here: https://github.com/Kong/kong/issues/3307

Below is what I suggested.

“I like to request if at all possible for Kong to provide as part of their admin api documentation swagger docs so that it easier to work with the API in a adhoc basis including interrupting with other products like postman, api generators etc.”

Please note that there is a few replies in the github ticket that i would suggest ppl read before posting.

Regards


#2

It is really a good idea.
AWS api gateway also has this useful feature.


#3

We have a couple of partial Swagger spec files for Kong’s Admin API currently:

We intend to release a more-complete Admin API specification file in the coming months.


#4

Hello,
Indeed it would be nice to have complete Swagger doc for admin API. This would allow the community to easily develop and maintain API client libs, as swagger comes with a code generator. Event if the code is not perfect, it permits to implement new API quickly and maintainer would not have to implement it themself after each release which update admin API.

What can we do to help you?


#5

What can we do to help you?

Thanks for the question @nmeylan ! Kong and Kong’s documentation are open source. We would welcome PRs to add an OpenAPI Spec (OAS - formerly known as Swagger) for the Kong Admin API. Likely you’d start by hand-crafting the spec, and adding it to our docs site via a pull request https://github.com/Kong/docs.konghq.com/ - if you want to get fancy, you could add OAS auto-generation to Kong core, though this will require a different skill set.

Note that the Kong Admin API changes, depending on what plugins and features are enabled - thus, it seems likely that whatever OAS you “manually” produce will only ever be partly complete. But don’t let this dissuade you - some spec is better than none :slight_smile:


#6

I think a Kong hosted swagger doc for the admin API that either the team or community members can update/contribute too would be absolutely awesome. Imagine how easy it will be for beginners to just take that doc and call their gateway using the swagger doc for updating resources quickly getting their hands dirty. I personally have just a ton of curl commands stored off in a github repo I use when not using the open source Konga UI tool I leverage today.

I think its important to find a way to incorporate auth into the swagger if possible(or maybe that requires modifications not stored in the doc but in the actual swagger parser ui itself?), like OAuth2.0 client creds support or a way to add a JWT on the call, because realistically people should have their admin api endpoints protected with auth from the gateway itself too.