KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation

[vnikolova]

KTOR-9165
KTOR-9193

• Add documentation for runtime route annotations
• Update compiler plugin docs for new configuration options
• add "what's new" sections
• Add a sample project
• Remove experimental label
• update the Swagger UI and OpenAPI plugin topics

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[bjhham]

For 3.4.0, we're updating the comment API style from KDoc tags to use a custom markdown format, due to some concerns over the tags potentially causing some unexpected behaviour in the IDE and KDoc processing. I just changed this last week after some comments from @whyoleg, so it's pretty last-minute 😅

So now all these keywords instead just need to be at the start of the line with a colon divider to designate the value:

/**
 * Get a list of widgets.
 *
 * - Tags:
 *   - widgets
 *   - admin
 * - Cookie: X-Analytics-Session some tracking cookie
 * - Responses:
 *   - 200 application/json [Widget]+ A list of widgets
 *   - 400 Invalid request
 */

Note, the plural form with tags and responses is an optional format, you can also use Tag: widgets, and the list bullets at the top level are also optional and just a matter of preference for formatting.

[vnikolova]

Thanks for the tip. I've updated the section to reflect the changes.

[bjhham]

I'm not sure if we have good documentation for the difference between the two plugins. I don't really know the full extent of the differences, but from what I can tell the main difference is that the OpenAPI renders the HTML from the provided model on the back end, and SwaggerUI renders the details from the front end and exposes the model endpoint as JSON or YAML. I would say the Swagger plugin ought to be the default implementation since it's a more modern UI and it's easier to navigate. Maybe @e5l could have some thoughts on this.

[vnikolova]

Added a couple of bullet points to clarify the difference between the two and updated the plugin topics.

[bjhham]

Added some comments wrt some API changes going in before the release.

Other important changes:

• The annotate function changed to describe and it now requires @OptIn(ExperimentalKtorApi::class)
• I'm intoducing an opposite function hide() that is called by default for the OpenAPI / Swagger plugins so that you can use the default source and it won't include these endpoints in the resulting document. This can be used for any internal endpoints that you don't want published.

See changes here ktorio/ktor#5300 and here ktorio/ktor#5308

[vnikolova]

Thanks for the review @danil-pavlov 🙏
I now committed your suggestions and left a couple comments.