Search⌘ K
AI Features
Home
Courses
Pure Functional HTTP APIs in Scala

Documentation via OpenAPI

Explore how to document HTTP APIs in Scala using the Tapir library and OpenAPI standards. Learn to generate Swagger UI documentation, add descriptions, status codes, and example data to your endpoints for clearer API communication and improved developer experience.

We'll cover the following...

Provide Swagger UI and documentation

We can now look at documenting our API via OpenAPI using the tooling provided by tapir. But first, we should modify our main application entry point to provide the documentation for us.

Scala
//...
productRoutes = new ProductRoutes(repo)
productsRoutes = new ProductsRoutes(repo)
docs = List(
    ProductRoutes.getProduct,
    ProductRoutes.updateProduct,
    ProductsRoutes.getProducts,
    ProductsRoutes.createProduct
).toOpenAPI("Pure Tapir API", "1.0.0")
docsRoutes = new SwaggerHttp4s(docs.toYaml)
routes = productRoutes.routes <+> productsRoutes.routes
httpApp = Router(
    "/" -> routes,
    "/docs" -> docsRoutes.routes
).orNotFound
//...

We use the toOpenAPI helper provided by tapir, which generates a class structure describing our API from a list of given endpoints (Line 9). Additionally, we use the SwaggerHttp4s helper, which includes the Swagger UI for ...