`OpenAPI` `Swagger` Ktor provides plugins for <Ope...

# ktor

[Jonas TM]

OpenAPI Swagger
Ktor provides plugins for OpenAPI and Swagger. However the documentation is quite limited. Is there currently any way to add information to the documentation like general API infos and single endpoint descriptions? Both plugins also seem to ignore the POST body definitions, is this a known problem?

[e5l]

@Vadim Briliantov could you check?

[Vadim Briliantov]

Hi @Jonas TM ! Thanks for your question!
Just to clarify, am I correct that your question is about IntelliJ action to generate OpenApi automatically based on your code?

Or is it about ktor plugins that provide routes to serve OpenApi/Swagger?

[Jonas TM]

Its about the Ktor plugin that provides the routes. But its also automatically generated the swagger files if I am correct. (At least its doing that in my project 😇~)~

[Vadim Briliantov]

Thanks!
Could you please check the resources/openapi/documentation.yaml ? Is there any issues with the post bodies?

[Jonas TM]

Sorry was confusing two things here. (Recently took over a Ktor project). Seems like the files were generated by IDE.

[Jonas TM]

So yes the problem lies there.

[Jonas TM]

Is it planned to be able to add documentation in code. Similar to plugins like this:
https://tegral.zoroark.guru/docs/modules/core/openapi/ktor

[Vadim Briliantov]

No, unfortunately, there are no plans to add wrappers around Ktor framework that allow annotating routes with documentation.
One of the main reasons behind this is that such solutions don’t check that documentation matches the real code usage 1:1 and it would require a compiler plugin to achieve this. While writing compiler plugins is currently out of scope for our team.

At the same time, we will be aiming to provide as good support of this functionality in IDE as possible. In the future we are planning to cover most of the popular use cases with our IDE action so that it generates OpenApi documentation that is 100% consistent with your code.

Thanks for your report, we’ll so our best to fix the POST issue that you mentioned asap

[Jonas TM]

Thanks for the detailed answer!

[Vadim Briliantov]

As for the general API infos and endpoint descriptions, what kind of descriptions do you mean?

Currently you could add kdoc comments or normal kotlin comments above your routes or Resource classes, and they will appear in the OpenAPI file after re-generation.

[Vadim Briliantov]

You can also add comments on bodies and responses— they’ll be also transferred to OpenApi descriptions automatically

[Vadim Briliantov]

Does that cover your needs?

[Jonas TM]

Yes thanks that should cover my cases.
Is there a way to trigger the spec file generation in a CI pipeline?

[Vadim Briliantov]

We are working on that, and we plan to offer a solution that will allow running IntelliJ actions from CI. Stay tuned 🙂

[Jonas TM]

Awesome, thanks!

[Jonas TM]

Could you point to an example where kdoc is used to add more infos to an endpoint for the generated spec? I am struggling to get it working.
The IntelliJ page is unfortunately not giving any details here:

Documentation comments for a specific route are used as endpoint descriptions

[Vadim Briliantov]

Here is an example of code and OpenAPI that was generated from this code:

[Vadim Briliantov]

Nota that It also supports requests and responses of custom types, for example:

[Jonas TM]

Thanks figured out the problem. Was correctly generated but the IntelliJ Swagger Preview is not updating automatically (only after close and reopening visible).

[Jonas TM]

However still having a problem with POST request body missing (see picture)

[Vadim Briliantov]

The issue with POST body is already fixed in the IntelliJ nightly. It will be soon published as 2023.1 I believe 🙂

[Jonas TM]

Thanks for jumping so quickly on the issue!

I got two other things on my mind regarding the generation:
• Is there a way to define tags via kdoc? Since otherwise all routes land under default section.
• We use the StatusPages plugin to return a specific error object in case something goes wrong. Would it possible to include this in the spec generation? I am guessing this one is a bit more tricky to do automatically. Maybe some way to define possible errors responses in kdoc would be a simple solution.

install(StatusPages) {
   exception<CustomApiException> { call, e ->
       call.respond(e.statusCode, ErrorResp(e.message))
    }
}

get("/test") {
    throw CustomApiException("some error reason returned to caller")
}

[Vadim Briliantov]

Is there a way to define tags via kdoc

Unfortunately, at the moment there is no way to do this. But we are planning to support Tags as well at some point. I can’t tell you what would be the solution for this, but I hope we’ll come up with something nice 🙂

We use the StatusPages plugin to return a specific error object in case something goes wrong. Would it possible to include this in the spec generation?

Yes! StatusPages support is already implemented and will be also available in the upcoming IDE releases. Maybe it will become available a bit later than POST bodies but anyway in the nearest future

[Jonas TM]

Thanks for the update. Awesome!