gzwytest04 / apidocs

Examples and comparison of how a REST API can be documented with different technologies

OpenAPI - code first or design first?

Overview

Let’s say that you’re given the task of writing a microservice AND providing a documentation in OpenAPI format. You already know that there are two main approaches:

• design-first : write the OpenAPI document (a.k.a. the openapi.yaml file) and then generate the code

• code-first : write the code, using OpenAPI annotations, and then generate the OpenAPI document

This repository contains different implementations of a simple service to demonstrate differences between the design-first and code-first approach.

Accompanying presentation at eclipsecon Europe 2019 : MicroProfile OpenAPI - code first or design first?

The examples use Quarkus and OpenLiberty as servers just because they not only support MicroProfile OpenAPI, but come also with an integrated UI. But the examples should run with very few code changes in any MicroProfile compatible server.

Code First

• code-first with OpenLiberty server and MicroProfile OpenAPI

• code-first with Quarkus server and MicroProfile OpenAPI

• code-first with Swagger scanner running with Quarkus server

Design First

• design-first with OpenAPI Generator and Quarkus server

• design-first with Swagger Codegen and Quarkus server

• design-first with Swagger Codegen and OpenLiberty server

Project Structure

The example projects all work without the parent umbrella project, so you can easily copy just the example you’re interested in and start modifying it.

All example projects have integration tests (in OpenapiDocumentIT.java) that check the result of the /openapi endpoint. Not only protects this from silent changes due to a changed implementation when the project dependencies are updated (like it happened when I updated from Quarkus 0.21.1 to 0.23.2), but it allows also to easily compare the differences between the example projects:

• every project contains a src/test/resources/openapi-sorted.yaml file with a little bit normalized OpenAPI document (sorting YAML files ist not trivial…​)

• the design-first projects contain also the generated POJO files as Xxx.java.txt files (the txt suffix protects them from being recognized as Java files by the IDE and being reformatted), allowing to compare the result of openapi-generator and swagger-codegen.

In addition all example projects have a rest-api.http file which allows to run some example HTTP request against a running service directly from within IntelliJ. And there is an _idea directory containing the IntelliJ project setup. But you can import the projects easily in any IDE with Maven support.

Comparison

Comparison between the examples using code-first and design-first approach

Solution	Pros	Cons
code-first	No need to learn OpenAPI Documents Project can just be opened in the IDE (No need to generate code first)	Portability: not every scanner creates the same openapi.yaml Portability: minor differences between Swagger and MicroProfile annotations Boilerplate and code duplication
design-first	One source of truth: Code, Documentation and Annotations generated from the same information can generate also Bean Validation annotations and Javadoc	Learning Effort IDE integration not optimal yet

Links

• MicroProfile OpenAPI Specification

  • Annotation Examples

  • YAML Output Examples

• OpenAPI Specification

  • OpenAPI Specification (OpenAPI Initiative)

  • OpenAPI Specification (Swagger)

• Quarkus - Using OpenAPI and Swagger UI

• OpenLiberty Guide - Documenting RESTful APIs