Difficulty: Beginner
Estimated Time: 35 Minutes

The definition of each step of this tutorial can be found at https://github.com/devonfw-tutorials/tutorials/tree/main/openapi-generation-servicedocgen.

Feel free to report any errors to us or fix them yourself. Errors can be reported by creating an issue in the tutorials repository. To fix the error fork the repository and create a pull request. Errors in the wiki can be reported and fixed in the tutorial-compiler repository. You can find a description of what to look for when creating a pull request at the devonfw contribution guide: https://devonfw.com/website/pages/community/community.html#community.asciidoc_contributing-to-devonfw. If you want to create a tutorial you can start with the katacoda tutorial and read the description for creating your own tutorials: https://github.com/devonfw-tutorials/tutorials/wiki/Development.

This tutorial will teach you how to use the ServicedocGen maven plugin to generate the OpenAPI specification and Swagger UI from your REST APIs.

The plugin analysis the REST APIs and the associated JavaDoc and then generates the OpenAPI specification as a static file. It is also able to create an HTML file that represents the Swagger UI and can be served by Quarkus to provide the Swagger UI in the browser.

For more information about OpenAPI and the ServicedocGen plugin, see the devon4j documentation.

#

Prerequisites

  • Installed devonfw-ide (or at least Java and Maven installed)

#

Learning goals

  • You will learn how to generate OpenAPI specifications and Swagger UI from REST services using ServicedocGen maven plugin

OpenAPI and Swagger UI generation with ServicedocGen plugin

Step 1 of 6

Clone quarkus-quickstarts repository

First, clone the quarkus-quickstarts repository from GitHub. It contains several sample applications for many extensions to Quarkus. For this tutorial, we will use an application with a simple REST service contained in the rest-json-quickstart subfolder.

Please change the folder to 'devonfw/workspaces/main'.

cd devonfw/workspaces/main

Now clone the repository to your local directory.

git clone https://github.com/quarkusio/quarkus-quickstarts.git