{"id":25019059,"url":"https://github.com/andrecaiado/spring-boot-openapi","last_synced_at":"2026-05-08T13:40:35.834Z","repository":{"id":275814450,"uuid":"849797187","full_name":"andrecaiado/spring-boot-openapi","owner":"andrecaiado","description":"Spring Boot demo project that implements API documentation using OpenApi specification and API-first approach","archived":false,"fork":false,"pushed_at":"2025-02-04T17:48:10.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-04T18:37:50.723Z","etag":null,"topics":["openapi","openapi-generator","openapi-specification","spring-boot"],"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/andrecaiado.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":"2024-08-30T09:09:58.000Z","updated_at":"2025-02-04T17:48:14.000Z","dependencies_parsed_at":"2025-02-04T18:38:00.676Z","dependency_job_id":"2ea07c63-ff07-47fa-adcf-d90b6c299455","html_url":"https://github.com/andrecaiado/spring-boot-openapi","commit_stats":null,"previous_names":["andrecaiado/spring-boot-openapi"],"tags_count":0,"template":false,"template_full_name":"andrecaiado/spring-boot-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrecaiado","download_url":"https://codeload.github.com/andrecaiado/spring-boot-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246297309,"owners_count":20754767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["openapi","openapi-generator","openapi-specification","spring-boot"],"created_at":"2025-02-05T11:19:54.983Z","updated_at":"2026-05-08T13:40:35.775Z","avatar_url":"https://github.com/andrecaiado.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Boot OpenAPI demo project\n\nThis is a Spring Boot demo project that implements API documentation using OpenApi specification and API-first approach.\n\n# Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n  - [Installation](#installation)\n- [Implementation](#implementation)\n  - [Create the project structure](#create-the-project-structure)\n    - [Create the modules](#create-the-modules)\n    - [Update the modules](#update-the-modules)\n  - [Generate the code](#generate-the-code)\n    - [Configure the code generator plugin](#configure-the-code-generator-plugin)\n    - [Define the OpenAPI specification](#define-the-openapi-specification)\n    - [Type mappings and import mappings](#type-mappings-and-import-mappings)\n      - [The OffsetDateTime mapping](#the-offsetdatetime-mapping)\n      - [The Pageable mapping](#the-pageable-mapping)\n    - [Generate the code](#generate-the-code)\n  - [Use the generated code in the project](#use-the-generated-code-in-the-project)\n    - [Accessing the generated resources](#accessing-the-generated-resources)\n    - [Implement the controllers](#implement-the-controllers)\n    - [Accessing the DTOs](#accessing-the-dtos)\n\n# Features\n\nThis project's main features are:\n\n- Generates the controllers and DTOs (as Java Records) based on the OpenAPI specification.\n- Generates OpenAPI documentation for the API.\n\n**Note:**\n\nThis readme file will focus on the OpenAPI documentation and API-first implementation. For more details about the other features of this project, please refer to the [Spring Boot Template project](https://github.com/andrecaiado/spring-boot-template) that was used as a base for this project.\n\n# Requirements\n\n- Java 17\n- Docker\n- Docker Compose\n\n# Getting Started\n\nThis section provides a step-by-step guide on how to run the project.\n\n## Installation\n\n1. Clone the repository by executing the following command:\n\n```shell\ngit clone https://github.com/andrecaiado/spring-boot-openapi.git\n```\n\n2. Navigate into the `spec` directory:\n\n```shell\ncd spring-boot-openapi/spec\n```\n\n3. Generate the code from the OpenAPI specification by executing the following command:\n\n```shell\n../mvnw clean compile\n```\n\n4. Navigate to the `impl` directory:\n\n```shell\ncd ../impl\n```\n\n5. Install the project dependencies by executing the following command:\n\n```shell\n../mvnw clean install\n```\n\n6. Run the application by executing the following command:\n\n```shell \n../mvnw spring-boot:run\n```\n\n## Try it out the API\n\nThe API can be tested using the Swagger UI or Postman.\n - The API documentation is available at [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html).\n- The Postman collection is available here: [spring-boot-template-rest-api.postman_collection.json](spring-boot-template-rest-api.postman_collection.json)\n\n# Implementation\n\nThis section provides a brief explanation of the implementation details of the project.\n\n## Create the project structure\n\nTo implement the API-first approach, the project is divided into the following modules:\n\n- **spec**: Contains the OpenAPI specification file.\n- **impl**: Contains the project's implementation, including the generated controllers and DTOs based on the OpenAPI specification.\n\n### Create the modules\n\nThe modules were created using IntelliJ. The steps to create a new module are:\n\n1. Right-click on the project's root directory.\n2. Select \"New\" -\u003e \"Module\".\n3. Provide a name for the module and click \"Finish\".\n\nAfter creating the `impl` module, delete this module's `src` folder and move the project's existing `src` directory to the new module.\n\nAfter creating the `spec` module, one can delete this module's `java` folder.\n\n### Update the modules\n\nTo update the `pom.xml` file, move the dependencies and plugins from the project's root `pom.xml` file to the `impl` module's `pom.xml` file.\n\n## Generate the code\n\nThis section provides a step-by-step guide on how to generate the controllers and DTOs based on the OpenAPI specification.\n\n### Configure the code generator plugin\n\nTo generate the controllers and DTOs based on the OpenAPI specification, the `openapi-generator-maven-plugin` plugin is used. The plugin configuration is defined in the `spec` module's [pom.xml](spec%2Fpom.xml) file.\n\nTo have a better understanding of the plugin configuration, please refer to the [openapi-generator-maven-plugin documentation](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin).\n\n### Define the OpenAPI specification\n\nCreate a `yaml` file in the `spec` module's `src/main/resources` directory. In this project, the OpenAPI specification is defined in the [openapi.yaml](spec%2Fsrc%2Fmain%2Fresources%2Fopenapi.yaml) file.\n\nThe OpenAPI specification file should contain the API's endpoints, request and response bodies, and other relevant information.\n\nThe OpenAPI specification file can be created manually or using a tool like [Swagger Editor](https://editor.swagger.io/).\n\nPlease refer to the [OpenAPI Specification documentation](https://swagger.io/docs/specification/about/) for more details on how to define the API's endpoints and models.\n\n### Type mappings and import mappings\n\nType mappings and import mappings allow for types bound to the OpenAPI Specification's types to be remapped to a user's desired types.\n\n- The `typeMappings` property is used to defines the user's target type for a given OpenAPI Specification type.\n- The `importMappings` informs the template of the type to be imported.\n\nThe `typeMappings` and `importMappings` properties are defined in the `configuration` section of the plugin configuration. In this project, the `typeMappings` and `importMappings` properties are defined in the `spec`module [pom.xml](spec%2Fpom.xml) file as shown below:\n\n```xml\n\u003cconfiguration\u003e\n    \u003ctypeMappings\u003e\n        \u003ctypeMapping\u003eOffsetDateTime=LocalDateTime\u003c/typeMapping\u003e\n        \u003ctypeMapping\u003ePageable=org.springframework.data.domain.Pageable\u003c/typeMapping\u003e\n    \u003c/typeMappings\u003e\n    \u003cimportMappings\u003e\n        \u003cimportMapping\u003eLocalDateTime=java.time.LocalDateTime\u003c/importMapping\u003e\n        \u003cimportMapping\u003ePageable=org.springframework.data.domain.Pageable\u003c/importMapping\u003e\n    \u003c/importMappings\u003e\n\u003c/configuration\u003e\n```\nThe `typeMappings` and `importMappings` properties are optional. If they are not defined, the default mappings will be used.\n\n#### The OffsetDateTime mapping\n\nIn this project, we are mapping the OffsetDateTime type to LocalDateTime.\nThis mapping is necessary because the OpenAPI specification uses OffsetDateTime for date-time fields however, the project uses LocalDateTime.\n\nWe also need to import the LocalDateTime class in the generated code, so we need to define the import mapping.\n\n#### The Pageable mapping\n\nIn this project, we are mapping the Pageable type to org.springframework.data.domain.Pageable.\nBecause there is no Pageable type in the OpenAPI specification, we defined a custom type in the OpenAPI specification and so, we need to map it to the Spring Pageable type.\n\nWe also need to import the Pageable class in the generated code, so we need to define the import mapping.\n\n### Generate the code\n\nTo generate the controllers and DTOs based on the OpenAPI specification, execute the following command:\n\n```shell\n./mvnw clean compile\n```\n\nThe plugin itself is defined to be triggered when the `compile` phase is triggered.\n\nAfter executing the command, the generated code will be available in the `target` directory of the `spec` module:\n- Controllers: `target/generated-sources/openapi/src/main/java/com/example/springbootopenapi/controller`\n- DTOs: `target/generated-sources/openapi/src/main/java/com/example/springbootopenapi/dto`\n\nThese locations were defined in the `openapi-generator-maven-plugin` plugin configuration.\n\n## Use the generated code in the project\n\nThis section provides a brief explanation of how to use the generated code in the project.\n\n### Accessing the generated resources\n\nIn order to access the generated resources, the `impl` module's [pom.xml](impl%2Fpom.xml) file should be updated to include the `spec` module as a dependency.\n\nFirst, we need to configure the dependency management in the main [pom.xml](pom.xml) file:\n\n```xml\n\u003cdependencyManagement\u003e\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.example\u003c/groupId\u003e\n      \u003cartifactId\u003espec\u003c/artifactId\u003e\n      \u003cversion\u003e0.0.1-SNAPSHOT\u003c/version\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\nThen, we need to add the `spec` module as a dependency in the `impl` module's [pom.xml](impl%2Fpom.xml) file:\n\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.example\u003c/groupId\u003e\n    \u003cartifactId\u003espec\u003c/artifactId\u003e\n    \u003cversion\u003e0.0.1-SNAPSHOT\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Implement the controllers\n\nIn the `impl` module, create a new package to store the controllers. The controllers should then implement the interfaces that were generated based on the OpenAPI specification and that are available in the `generated-sources` directory.\n\n**Note:**\nThe above-mentioned interfaces were made available to the `impl` module as it was explained in the previous section.\n\n**Example for the EmployeeController:**\n\nThe `EmployeeApi` interface contains the methods that should be implemented by the controller. The `EmployeeController` class implements the `EmployeeApi` interface and provides the implementation for the methods.\n\nThe example below shows the EmployeeController class after specifying that it implements the EmployeeApi interface and overriding the methods. All that is left to do is to implement the methods.\n\n```java\n@RestController\n@RequestMapping(\"/api/v1/employees\")\npublic class EmployeeController implements EmployeeApi {\n\n  private final EmployeeService employeeService;\n\n  public EmployeeController(EmployeeService employeeService) {\n    this.employeeService = employeeService;\n  }\n\n  @Override\n  public ResponseEntity\u003cString\u003e deleteEmployeeById(Integer id) {\n    return null;\n  }\n\n  @Override\n  public ResponseEntity\u003cList\u003cEmployeeDto\u003e\u003e getAllEmployees(Pageable pageable) {\n    return null;\n  }\n\n  @Override\n  public ResponseEntity\u003cEmployeeDto\u003e getEmployeeById(Integer id) {\n    return null;\n  }\n\n  @Override\n  public ResponseEntity\u003cEmployeeDto\u003e saveEmployee(CreateEmployeeDto createEmployeeDto) {\n    return null;\n  }\n\n  @Override\n  public ResponseEntity\u003cEmployeeDto\u003e updateEmployee(Integer id, CreateEmployeeDto createEmployeeDto) {\n    return null;\n  }\n}\n```\n\n### Accessing the DTOs\n\nThe DTOs are available in the `generated-sources` directory. To use the DTOs, import the classes in the controller classes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecaiado%2Fspring-boot-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrecaiado%2Fspring-boot-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecaiado%2Fspring-boot-openapi/lists"}