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

• design-first : write the OpenAPI document (a.k.a. theopenapi.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 differencesbetween the design-first and code-first approach.

Accompanying presentation ateclipsecon Europe 2019 :MicroProfile OpenAPI - code first or design first?,Talk on Youtube

The examples useQuarkus as serverjust because it not only supports MicroProfile OpenAPI, but comes also with an integrated UI.But the examples should run with very few code changes in any MicroProfile compatible server.

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

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

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

• thedesign-first projects contain also the generated POJO files asXxx.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 arest-api.http file which allows to run some example HTTPrequest against a running service directly from within IntelliJ. And there is an_idea directorycontaining the IntelliJ project setup. But you can import the projects easily in any IDE with Mavensupport.

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

• MicroProfile OpenAPI Specification

  • Annotation Examples

  • YAML Output Examples

• OpenAPI Specification

  • OpenAPI Specification (OpenAPI Initiative)

  • OpenAPI Specification (Swagger)

• Quarkus - Using OpenAPI and Swagger UI