https://github.com/pe-st/apidocs
Examples and comparison of how a REST API can be documented with different technologies
https://github.com/pe-st/apidocs
java microprofile openapi
Last synced: 13 days ago
JSON representation
Examples and comparison of how a REST API can be documented with different technologies
- Host: GitHub
- URL: https://github.com/pe-st/apidocs
- Owner: pe-st
- License: mit
- Created: 2019-03-06T13:40:06.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-11-15T21:40:43.000Z (2 months ago)
- Last Synced: 2025-11-15T23:27:33.088Z (2 months ago)
- Topics: java, microprofile, openapi
- Language: Java
- Homepage:
- Size: 8.01 MB
- Stars: 7
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= OpenAPI - code first or design first?
image:https://github.com/pe-st/apidocs/actions/workflows/maven/badge.svg?branch=feature%2Fupdates["Build Status"]
== 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 https://web.archive.org/web/20240720193801/https://www.eclipsecon.org/europe2019[eclipsecon Europe 2019] :
https://web.archive.org/web/20240525183216/https://www.eclipsecon.org/europe2019/sessions/microprofile-openapi-code-first-or-design-first[MicroProfile OpenAPI - code first or design first?],
https://www.youtube.com/watch?v=vnCuFk1Ayqs[Talk on Youtube]
The examples use https://quarkus.io/[Quarkus] as server
just 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.
=== Code First
* link:code-first-openapi-quarkus/README.md[code-first with Quarkus server and MicroProfile OpenAPI]
* link:code-first-swagger/README.md[code-first with Swagger scanner running with Quarkus server]
=== Design First
* link:design-first-openapi-generator/README.md[design-first with OpenAPI Generator and Quarkus server]
* link:design-first-swagger-quarkus/README.md[design-first with Swagger Codegen and Quarkus 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
[cols="1,2a,2a"]
|===
|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
* https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#operation[MicroProfile OpenAPI Specification]
** https://github.com/eclipse/microprofile-open-api/wiki/Annotation-Samples[Annotation Examples]
** https://github.com/eclipse/microprofile-open-api/wiki/Static-File-Samples[YAML Output Examples]
* OpenAPI Specification
** https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md[OpenAPI Specification (OpenAPI Initiative)]
** https://swagger.io/specification/[OpenAPI Specification (Swagger)]
* https://quarkus.io/guides/openapi-swaggerui-guide[Quarkus - Using OpenAPI and Swagger UI]