{"id":37442057,"url":"https://github.com/pe-st/apidocs","last_synced_at":"2026-01-16T06:45:37.526Z","repository":{"id":88295267,"uuid":"174152338","full_name":"pe-st/apidocs","owner":"pe-st","description":"Examples and comparison of how a REST API can be documented with different technologies","archived":false,"fork":false,"pushed_at":"2025-11-15T21:40:43.000Z","size":8395,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-15T23:27:33.088Z","etag":null,"topics":["java","microprofile","openapi"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pe-st.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-03-06T13:40:06.000Z","updated_at":"2024-11-20T18:37:12.000Z","dependencies_parsed_at":"2025-10-16T18:38:44.085Z","dependency_job_id":"4d992702-5820-4fa6-9cdd-22f8dfa0a73c","html_url":"https://github.com/pe-st/apidocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pe-st/apidocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pe-st%2Fapidocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pe-st%2Fapidocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pe-st%2Fapidocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pe-st%2Fapidocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pe-st","download_url":"https://codeload.github.com/pe-st/apidocs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pe-st%2Fapidocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","microprofile","openapi"],"created_at":"2026-01-16T06:45:37.462Z","updated_at":"2026-01-16T06:45:37.518Z","avatar_url":"https://github.com/pe-st.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= OpenAPI - code first or design first?\n\nimage:https://github.com/pe-st/apidocs/actions/workflows/maven/badge.svg?branch=feature%2Fupdates[\"Build Status\"]\n\n== Overview\n\nLet's say that you're given the task of writing a microservice *AND* providing a documentation\nin OpenAPI format. You already know that there are two main approaches:\n\n* design-first : write the OpenAPI document (a.k.a. the `openapi.yaml` file) and then generate the code\n* code-first : write the code, using OpenAPI annotations, and then generate the OpenAPI document\n\nThis repository contains different implementations of a simple service to demonstrate differences\nbetween the design-first and code-first approach.\n\nAccompanying presentation at https://web.archive.org/web/20240720193801/https://www.eclipsecon.org/europe2019[eclipsecon Europe 2019] :\nhttps://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?],\nhttps://www.youtube.com/watch?v=vnCuFk1Ayqs[Talk on Youtube]\n\nThe examples use https://quarkus.io/[Quarkus] as server\njust because it not only supports MicroProfile OpenAPI, but comes also with an integrated UI.\nBut the examples should run with very few code changes in any MicroProfile compatible server.\n\n=== Code First\n\n* link:code-first-openapi-quarkus/README.md[code-first with Quarkus server and MicroProfile OpenAPI]\n* link:code-first-swagger/README.md[code-first with Swagger scanner running with Quarkus server]\n\n=== Design First\n\n* link:design-first-openapi-generator/README.md[design-first with OpenAPI Generator and Quarkus server]\n* link:design-first-swagger-quarkus/README.md[design-first with Swagger Codegen and Quarkus server]\n\n== Project Structure\n\nThe example projects all work without the parent umbrella project, so you can easily copy just the\nexample you're interested in and start modifying it.\n\nAll example projects have integration tests (in `OpenapiDocumentIT.java`) that check the result of\nthe `/openapi` endpoint. Not only protects this from silent changes due to a changed implementation\nwhen the project dependencies are updated (like it happened when I updated from Quarkus 0.21.1 to\n0.23.2), but it allows also to easily compare the differences between the example projects:\n\n* every project contains a `src/test/resources/openapi-sorted.yaml` file with a little bit normalized\n  OpenAPI document (sorting YAML files ist not trivial...)\n* the _design-first_ projects contain also the generated POJO files as `Xxx.java.txt` files\n  (the txt suffix protects them from being recognized as Java files by the IDE and being reformatted),\n  allowing to compare the result of openapi-generator and swagger-codegen.\n\nIn addition, all example projects have a `rest-api.http` file which allows to run some example HTTP\nrequest against a running service directly from within IntelliJ. And there is an `_idea` directory\ncontaining the IntelliJ project setup. But you can import the projects easily in any IDE with Maven\nsupport.\n\n\n== Comparison\n\nComparison between the examples using code-first and design-first approach\n\n[cols=\"1,2a,2a\"]\n|===\n|Solution|Pros|Cons\n\n|code-first|\n* No need to learn OpenAPI Documents\n* Project can just be opened in the IDE (No need to generate code first)\n|\n* Portability: not every scanner creates the same `openapi.yaml`\n* Portability: minor differences between Swagger and MicroProfile annotations\n* Boilerplate and code duplication\n\n|design-first|\n* One source of truth:\nCode, Documentation and Annotations generated from the same information\n* can generate also Bean Validation annotations and Javadoc\n|\n* Learning Effort\n* IDE integration not optimal yet\n\n|===\n\n== Links\n\n* https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#operation[MicroProfile OpenAPI Specification]\n** https://github.com/eclipse/microprofile-open-api/wiki/Annotation-Samples[Annotation Examples]\n** https://github.com/eclipse/microprofile-open-api/wiki/Static-File-Samples[YAML Output Examples]\n* OpenAPI Specification\n** https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md[OpenAPI Specification (OpenAPI Initiative)]\n** https://swagger.io/specification/[OpenAPI Specification (Swagger)]\n* https://quarkus.io/guides/openapi-swaggerui-guide[Quarkus - Using OpenAPI and Swagger UI]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpe-st%2Fapidocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpe-st%2Fapidocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpe-st%2Fapidocs/lists"}