{"id":15091192,"url":"https://github.com/bzdgn/open-api-web-service-example","last_synced_at":"2026-02-12T15:31:21.840Z","repository":{"id":81112724,"uuid":"594733429","full_name":"bzdgn/open-api-web-service-example","owner":"bzdgn","description":"Demo Project for Open API Web Service with Spring Boot","archived":false,"fork":false,"pushed_at":"2023-01-29T20:38:21.000Z","size":506,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-24T14:42:31.025Z","etag":null,"topics":["java","open-api","open-api-specification","open-api-v3","openapi","openapi-generator","openapi-specification","openapi3","spring-boot","web-service"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bzdgn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-01-29T13:35:15.000Z","updated_at":"2024-04-18T22:57:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"dc836718-ed3d-42b0-9163-40ee5dbf84fb","html_url":"https://github.com/bzdgn/open-api-web-service-example","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"98b0f170bec9300974ea9adb596f7b07e2c85d08"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bzdgn/open-api-web-service-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdgn%2Fopen-api-web-service-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdgn%2Fopen-api-web-service-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdgn%2Fopen-api-web-service-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdgn%2Fopen-api-web-service-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bzdgn","download_url":"https://codeload.github.com/bzdgn/open-api-web-service-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdgn%2Fopen-api-web-service-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29370546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"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","open-api","open-api-specification","open-api-v3","openapi","openapi-generator","openapi-specification","openapi3","spring-boot","web-service"],"created_at":"2024-09-25T10:36:18.563Z","updated_at":"2026-02-12T15:31:21.826Z","avatar_url":"https://github.com/bzdgn.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"This project is a demonstration of OpenAPI Web Service with Spring Boot.\n\nTOC\n---\n- [0 Introduction](#0-introduction) \u003cbr/\u003e\n- [1 Setup](#1-setup) \u003cbr/\u003e\n- [2 OpenAPI Specs](#2-openapi-specs) \u003cbr/\u003e\n- [3 OpenAPI Plugin](#3-openapi-plugin) \u003cbr/\u003e\n- [4 Testing with Postman Collection](#4-testing-with-postman-collection)\u003cbr/\u003e\n\n 0 Introduction\n---------------\nThis project is a demonstration of OpenAPI Web Service with Spring Boot.\n\nWith OpenAPI, you can define the models and your service specifications in yaml format and build the skeleton of your web service.\n\nThere are good and bad parts and I'm going to list my personal opinions;\n\nThe good parts of OpenAPI are;\n\n- The boilerplate code is automatically generated\n- You can define the models within the yaml files and they are auto-generated\n- The endpoint skeleton is also generated. You can either use the generated controller or override it to customize it.\n\nThe bad parts of OpenAPI are;\n\n- You need to dig around the documentation and the net for the use of plugins\n- It adds complexity when you are using OpenAPI within a multi-module project\n- Using the generated models in a distinct shared project and injecting the resources is not easy\n\nIn this project, I'm not going to dive into these topics. This project will give you a simple example of OpenAPI web service.\n\n\n[TOC](#toc)\n\n\n 1 Setup\n--------\nWe use OpenAPI to generate models, generate a template for the web service and also helper classes. So that within one simple yaml file, the model classes and also the api template is generated for the controller of the web service.\n\nThere are two files that does the magic for the auto-generated code/template;\n\n- The OpenAPI spec file(s) in yaml format, that define(s) the web service skeleton and schemas. These file(s) placed in the **src/main/resources/openapi** folder.\n- The build plugin that generates the code based on the OpenAPI yaml file. This is defined in the **pom** file.\n\nIn the pom file, build/plugin section has reference for spec file and package names for model and service packages. Plugin uses the yaml spec and generates the model/service classes under the defined packages.\nThen these generated files are placed in the target/generated-sources/src folder as can be seen below;\n\n![generated_files](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/01_generated_files.PNG)\n\nAfter importing it to an IDE (I use eclipse), you need to add the OpenAPI generated code into the build path.\n\n1. The files need to be added will be under **target/generated-sources/src/main/java**\n\n![target_generated_files](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/02_target_generated_files.PNG)\n\n2. Right click to this folder and add it to the build path\n\n![right_click_generated_files](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/03_build_path.PNG)\n\n3. See the generated code is visible in the project\n\n![add_generated_files_to_build_path](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/04_added_build_path.PNG)\n\n\n[TOC](#toc)\n\n\n 2 OpenAPI Specs\n----------------\nThe spec file defines the endpoints, and the structure of the model classes those are used in endpoints. We have two get operations and one post operation. These operations uses Person model for request or response and one operation returns an array of Person model.\n\nYou can see the file in project sources [here](https://github.com/bzdgn/open-api-web-service-example/blob/main/src/main/resources/openapi/person-api.yaml). The content of the file is as follows;\n\n```yaml\nopenapi: 3.0.3\ninfo:\n  title: Person Service\n  description: Public service for querying the persons\n  version: 1.0\nservers:\n  - description: Local development environment\n    url: http://localhost:8080/v1\n  - description: Kubernetes test environment\n    url: http://some-link-here.com/v1\n  - description: Kubernetes acc environment\n    url: http://some-link-here.com/v1\n  - description: Kubernetes production environment\n    url: http://some-link-here.com/v1\n\npaths:\n  /person/{id}:\n    get:\n      operationId: getPerson\n      tags:\n        - person\n      parameters:\n        - name: id\n          in: path\n          description: person id\n          required: true\n          schema:\n            type: integer\n            format: int32\n      responses:\n        200:\n          description: Person results\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Person'\n        400:\n          description: not a valid person\n\n  /person:\n    get:\n      operationId: getPersons\n      tags:\n        - person\n      responses:\n        200:\n          description: Person results\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/PersonList'\n        400:\n          description: not a valid person\n\n    post:\n      operationId: addPerson\n      tags:\n        - person\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/Person'\n      responses:\n        200:\n          description: Zoekresultaten\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Person'\n        400:\n          description: not a valid person\n\ncomponents:\n  schemas:\n    Person:\n      type: object\n      properties:\n        id:\n          required: true\n          description: id of the person\n          type: integer\n          format: int32\n        name:\n          description: name of the person\n          type: string\n        age:\n          description: age of the person\n          type: integer\n          format: int32\n    PersonList:\n      type: array\n      items:\n        $ref: '#/components/schemas/Person' \n\n```\n\nUnder the **paths** section, the endpoint is defined. OpenAPI plugin will define the service classes based on this section. Under the **components** section there is **schemas** where the model classes are defined. OpenAPI will generate the model classes based on this section.\n\nImportant to notify that the service uses these generated models. If you use maven in command line, the generator will notify you if there are inconsistencies.\n\n\n[TOC](#toc)\n\n\n 3 OpenAPI Plugin\n-----------------\nOpenAPI plugin generates the code based on yaml specs. In the build [plugin section](https://github.com/bzdgn/open-api-web-service-example/blob/main/pom.xml);\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.openapitools\u003c/groupId\u003e\n            \u003cartifactId\u003eopenapi-generator-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e${openapi-generator-maven-plugin.version}\u003c/version\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cphase\u003egenerate-sources\u003c/phase\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003egenerate\u003c/goal\u003e\n                    \u003c/goals\u003e\n                    \u003cconfiguration\u003e\n                        \u003cinputSpec\u003e${project.basedir}/src/main/resources/openapi/person-api.yaml\u003c/inputSpec\u003e\n                        \u003cgeneratorName\u003espring\u003c/generatorName\u003e\n                        \u003coutput\u003e${project.build.directory}/generated-sources/\u003c/output\u003e\n                        \u003cgenerateModels\u003etrue\u003c/generateModels\u003e\n                        \u003cgenerateSupportingFiles\u003etrue\u003c/generateSupportingFiles\u003e\n                        \u003csupportingFilesToGenerate\u003eApiUtil.java\u003c/supportingFilesToGenerate\u003e\n                        \u003cmodelPackage\u003eio.github.bzdgn.open-api-web-service-example.model\u003c/modelPackage\u003e\n                        \u003capiPackage\u003eio.github.bzdgn.open-api-web-service-example.service\u003c/apiPackage\u003e\n                        \u003cskipValidateSpec\u003etrue\u003c/skipValidateSpec\u003e\n                        \u003cconfigOptions\u003e\n                            \u003cinterfaceOnly\u003etrue\u003c/interfaceOnly\u003e\n                            \u003cjava11\u003etrue\u003c/java11\u003e\n                            \u003cdateLibrary\u003ejava8\u003c/dateLibrary\u003e\n                            \u003copenApiNullable\u003efalse\u003c/openApiNullable\u003e\n                            \u003cdocumentationProvider\u003enone\u003c/documentationProvider\u003e\n                            \u003cannotationLibrary\u003enone\u003c/annotationLibrary\u003e\n                        \u003c/configOptions\u003e\n                        \u003cconfigHelp\u003efalse\u003c/configHelp\u003e\n                    \u003c/configuration\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\nIf you look at the configuration, a few keys are important;\n\n| variable | description |\n| -------- | ----------- |\n| inputSpec | This is where you reference your Api spec, in our example, it is the person-api.yaml file |\n| output | This is the output folder where all the generated code is placed. Under the project build directory, which is target, it's placed in **generated-sources** folder |\n| generateModels | This determines if the model classes are generated, set to **true** |\n| generateSupportingFiles | This is the utility file that plugin generates, set to **true** |\n| supportingFilesToGenerate | The name of the utility file, in our example **ApiUtil.java** |\n| modelPackage | The package that the model generated files placed |\n| apiPackage | The package that the service generated files  placed |\n| skipValidateSpec | Does the validation in the generation. It's set to **true** in this example but sometimes useful to set to **false** when using multimodule projects |\n\n\n[TOC](#toc)\n\n\n 4 Testing with Postman Collection\n----------------------------------\nI've placed a simple postman collection [under the misc folder, here](https://github.com/bzdgn/open-api-web-service-example/blob/main/misc/OpenAPIWebServiceExample.postman_collection.json). You need to import this collection in Postman to test the example web service.\n\n![postman_collection](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/05_postman_collection.PNG)\n\nInitially the **person** repository will be empty. The implemntation is a simple stub for testing, using an ArrayList to store the posted **Person** objects.\n\nYou can post via the Postman;\n\n![postman_collection_post_1](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/06_postman_post_1.PNG)\n![postman_collection_post_2](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/07_postman_post_2.PNG)\n\nThen you can get **Person** by id;\n\n![postman_collection_get_by_id](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/08_postman_get_by_id.PNG)\n\nOr you can the whole **Person** repository;\n\n![postman_collection_get_all](https://raw.githubusercontent.com/bzdgn/open-api-web-service-example/main/misc/09_postman_get_all.PNG)\n\n\n[TOC](#toc)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzdgn%2Fopen-api-web-service-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbzdgn%2Fopen-api-web-service-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzdgn%2Fopen-api-web-service-example/lists"}