Skip to content

Commit 9ca62d6

Browse files
OmarAlJarrahOmarAlJarrah
committed
chore: update architecture documentation for XAP SDK with additional module details and gradle tasks
1 parent 890b32c commit 9ca62d6

File tree

1 file changed

+60
-22
lines changed

1 file changed

+60
-22
lines changed

‎ARCHITECTURE.md‎

Lines changed: 60 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,23 @@
11
# Overview
22

3-
The XAP (Expedia API Platform) SDK is structured as a multi-module Gradle project designed to generate a Kotlin/Java SDK from OpenAPI specifications. The architecture follows a code generation approach, where API client code is automatically generated and then published to repositories for consumption by developers.
3+
The XAP (Expedia API Platform) SDK is structured as a multi-module Gradle project designed to generate a Kotlin/Java SDK
4+
from OpenAPI specifications. The architecture follows a code generation approach, where API client code is automatically
5+
generated and then published to repositories for consumption by developers.
46

57
The repository contains the following key components:
68

7-
| Component | Description |
8-
|----------------------------|----------------------------------------------------------------------------------------------------------------|
9-
| **OpenAPI Specifications** | Defines the API endpoints, request/response models, and data types |
10-
| **Code Generation** | Utilizes OpenAPI Generator to create the SDK code based on the specifications. |
11-
| **Core Integration** | Integrates with the Expedia Group's SDK platform core libraries and frameworks |
12-
| **Post-Processing** | Enhances the generated code with additional features, optimizations, and customizations |
13-
| **Publishing Tasks** | Automates the release process to make the SDK available for developers |
14-
| **Examples** | Provides sample applications demonstrating how to use the generated SDK |
15-
| **Documentation** | Contains guides and references for developers to understand and utilize the SDK effectively |
16-
| **Testing** | Includes unit, integration and end-to-end tests to ensure the correctness and reliability of the generated SDK |
17-
9+
| Component | Description |
10+
|---------------------------------|-----------------------------------------------------------------------------------------------------------------|
11+
| **OpenAPI Specifications** | Defines the API endpoints, request/response models, and data types. |
12+
| **Code Generation** | Utilizes OpenAPI Generator to create the SDK code based on the specifications. |
13+
| **Core Integration** | Integrates with the Expedia Group's SDK platform core libraries and frameworks. |
14+
| **Post-Processing** | Enhances the generated code with additional features, optimizations, and customizations. |
15+
| **Publishing Tasks** | Automates the release process to make the SDK available for developers. |
16+
| **Examples** | Provides sample applications demonstrating how to use the generated SDK. |
17+
| **Documentation** | Contains guides and references for developers to understand and utilize the SDK effectively. |
18+
| **Testing** | Includes unit, integration and end-to-end tests to ensure the correctness and reliability of the generated SDK. |
19+
| **OpenAPI Specification Files** | OpenAPI definitions. Located at `specs` directory in the root of the repository. |
20+
| **Gradle Helper Tasks** | Gradle tasks that automate common tasks. |
1821

1922
# Technology Stack
2023

@@ -34,26 +37,61 @@ The repository contains the following key components:
3437

3538
The project is organized into several modules, each serving a specific purpose. The main modules include:
3639

37-
## Generator Module
40+
## Root Module
41+
42+
The root module serves as the entry point for the project. It contains the overall project configuration, including
43+
dependency management, build scripts, and common configurations shared across all modules. This module also includes the
44+
`settings.gradle.kts` file, which defines the structure of the multi-module project.
45+
The module defines custom gradle tasks that live in the `gradle-tasks` directory. The defined tasks handle OpenAPI
46+
specification files pre-processing, publishing, as well as for generating and publishing the SDK to a remote repository.
47+
It also includes configurations for code quality checks, such as Ktlint and Kover. All tasks are defined using kotlin
48+
DSL.
49+
50+
| Defined Gradle Task | Description |
51+
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
52+
| `mergeSpecs` | Executes the openapi-merge-cli command using npx to merge OpenAPI specs. |
53+
| `transformSpecs` | Executes the spec-transformer CLI command using npx to transform the OpenAPI specs. |
54+
| `prepareSpecs` | A wrapper for the sequential execution of `mergeSpecs` and `transformSpecs`. Generates and copies a final specs.yaml file to the generator module's resources directory |
55+
56+
## Generator Module
57+
58+
The `generator` module is responsible for the core functionality of the SDK generation process. It consumes the OpenAPI
59+
specifications and generates the initial SDK code using OpenAPI Generator. It also integrates with the
60+
`expediagroup-sdk-openapi-plugin`.
3861

39-
The `generator` module is responsible for the core functionality of the SDK generation process. It consumes the OpenAPI specifications and generates the initial SDK code using OpenAPI Generator. It also integrates with the`expediagroup-sdk-openapi-plugin`.
62+
| Generator Component/Asset | Description |
63+
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
64+
| **OpenAPI Generator Configurations** | The core library that generates the SDK code from OpenAPI specifications. Lives in the `build.gradle.kts` file. |
65+
| **Custom Templates** | Custom templates for generating Kotlin/Java code. Lives in the `src/main/resources/templates` directory. |
66+
| **Post-Processing** | Enhancements and optimizations applied to the generated code. Lives in the `src/main/resources/post-processing` directory. |
4067

41-
| Generator Component/Asset | Description |
42-
|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
43-
| **OpenAPI Generator Configurations** | The core library that generates the SDK code from OpenAPI specifications. Lives in the `build.gradle.kts` file |
44-
| **Custom Templates** | Custom templates for generating Kotlin/Java code. Lives in the `src/main/resources/templates` directory |
45-
| **Post-Processing** | Enhancements and optimizations applied to the generated code. Lives in the `src/main/resources/post-processing` directory |
68+
The generation process can be executed through the `openApiGenerate` Gradle task, which triggers the OpenAPI Generator
69+
with the specified configurations.
4670

47-
The generation process can be executed through the `openApiGenerate` Gradle task, which triggers the OpenAPI Generator with the specified configurations.
4871
```shell
4972
gradle clean build
5073

5174
cd generator
5275
gradle openApiGenerate --stacktrace
5376
```
77+
5478
The `openApiGenerate` gradle task workflow is as follows:
55-
1. Locates the OpenAPI specification file through the `inputSpec` environment variable, falling back to `generator/src/main/resources/specs.yaml` if not found.
79+
80+
1. Locates the OpenAPI specification file through the `inputSpec` environment variable, falling back to
81+
`generator/src/main/resources/specs.yaml` if not found.
5682
2. Consumes the OpenAPI specification file to generates code into the `xap-sdk/src/main/kotlin` directory.
57-
3. Generated code overrides the code present `xap-sdk/src/main/kotlin` directory, affecting only the `operations` and `models` packages.
83+
3. Generated code overrides the code present `xap-sdk/src/main/kotlin` directory, affecting only the `operations` and
84+
`models` packages.
5885
4. The generated code is then post-processed to apply additional customizations and optimizations.
5986
5. Finally, the code is formatted and linted using Ktlint to ensure code quality and consistency.
87+
88+
## Build-Logic Module
89+
90+
The `buildSrc` module is
91+
a [Gradle build logic module](https://docs.gradle.org/current/userguide/sharing_build_logic_between_subprojects.html#sec:using_buildsrc)
92+
that contains custom Gradle plugins and shared build logic used across the project. It allows for better organization
93+
and reusability of build scripts and configurations.
94+
95+
The `buildSrc` module is used to define OpenAPI Generator customizations, such as custom mustache lambdas. This module
96+
can be used to define custom Gradle tasks, plugins, and other build-related logic that can be reused across the project.
97+
It is automatically included in the build process and can be used to extend the functionality of Gradle.

0 commit comments

Comments
 (0)