How to Build a Java SDK based on OpenAPI

APIs are one of the most important components in communication between services in modern software, and the OpenAPI Specification has become the go-to standard for defining them. But while building an API might seem straightforward, offering a smooth developer experience often depends on the availability of SDKs (Software Development Kits). SDKs simplify API integration by providing pre-built, language-specific libraries that developers can use to interact with APIs more efficiently.

Creating and maintaining SDKs manually for multiple programming languages can quickly become a time-consuming task. That's where automating the process as much as possible comes in handy. By leveraging the OpenAPI standard, you can automate the generation of SDKs, reducing maintenance time and ensuring consistency across different platforms.

In this guide, we’ll focus on how to build a Java SDK based on an OpenAPI specification. By the end of this tutorial, you’ll have a clear understanding of the following:

• How to build a Java SDK based on an OpenAPI specification?
• What are the necessary steps to go from an OpenAPI file to a full functional, deployable Java SDK?
• What are the best practices for building and maintaining SDKs?

We'll use Corbado’s passkey-first Java SDK as an example, guiding you through the practical steps and considerations involved in creating a professional, user-friendly SDK.

The prerequisites are pretty simple. You need a backend services that exposes an API. This API should be a RESTful API and you should have an OpenAPI specification of it available.

The first step in building a Java SDK from an OpenAPI specification is to use an OpenAPI generator to create a client SDK. The OpenAPI generator simplifies the process by automatically generating client-side code that interacts with your API.

Ideally, the generated client SDK should be placed in a separate project or repository. This ensures clean separation from your main application, helping to simplify dependency management. Generated SDKs often include third-party libraries that might not align with the dependencies used in your core project.

Subscribe to our Passkeys Substack for the latest news, insights and strategies.

Subscribe

Best Practice: Avoid Modifying Generated Code

It’s best practice to avoid manually modifying the generated code. Once you start editing the generated SDK code, it becomes difficult to keep up with future updates or regenerate the SDK when your OpenAPI specification changes. Instead, any custom functionality should be built on top of the generated code, not directly within it.

If you're concerned about exposing the complexities of the generated code to developers, decouple the generated code from your SDK interface. This way, the complexity remains hidden, and your SDK provides a clean, simple interface for developers to use.

When building a Java SDK from an OpenAPI specification, it’s important to first familiarize yourself with existing SDKs that can serve as role models (if they exist - in other cases you need to define the requirements for the SDK).

For Corbado’s Java Passkeys SDKs, two key scenarios include session validation and extracting additional user information. These features are important for developers integrating user authentication into their applications.

The goal of the SDK is to provide more than just a generated client. While a simple client offers basic API interaction, a well-built SDK enhances the developer experience by offering:

• A simple, easy-to-install library for connecting to the backend.
• Meaningful error handling, making it easier for developers to debug and resolve issues.
• Easy configuration, allowing developers to get started with minimal friction.
• Clear, documented examples for all available functionality (often provided through unit tests).
• A lower entry barrier for developers trying out the service for the first time.

Become part of our Passkeys Community for updates and support.

Join

An essential part of building the Corbado SDK is understanding how JSON Web Tokens (JWT) and JSON Web Keys (JWK) are handled, as these are used for session validation. You’ll want to:

• Familiarize yourself with JWT/JWK concepts
• Search for available JWT libraries for Java

A JWT validation process could include validating the signature, checking token expiration, and handling JWK errors with custom exceptions like JWTVerificationException or JwkException.

  private SessionValidationResult getAndValidateUserFromShortSessionValue(final String shortSession)
      throws JWTVerificationException, JwkException, IncorrectClaimException {
    if (shortSession == null || shortSession.isEmpty()) {
    throw new IllegalArgumentException("Session value cannot be null or empty");
    }
 
    try {
    // Decode the JWT without verifying it, to extract its claims and headers.
    DecodedJWT decodedJwt = JWT.decode(shortSession);
 
    // Retrieve the signing key (JWK) using the Key ID (kid) from the JWT header.
    final Jwk jwk = this.jwkProvider.get(decodedJwt.getKeyId());
 
    // If the signing key (JWK) is not found, throw a custom exception.
    if (jwk == null) {
        throw new SigningKeyNotFoundException(shortSession, null);
    }
 
    // Extract the RSA public key from the JWK for verifying the JWT.
    final RSAPublicKey publicKey = (RSAPublicKey) jwk.getPublicKey();
 
    // Define the RSA256 algorithm using the retrieved public key.
    final Algorithm algorithm = Algorithm.RSA256(publicKey);
 
    // Create a JWT verifier using the algorithm and expected issuer.
    final JWTVerifier verifier = JWT.require(algorithm).withIssuer(this.issuer).build();
 
    // Verify the JWT signature and decode the JWT.
    decodedJwt = verifier.verify(shortSession);
 
    // Build and return the session validation result, extracting claims like name and userID.
    return SessionValidationResult.builder()
        .fullName(decodedJwt.getClaim("name").asString()) // Extract the 'name' claim.
        .userID(decodedJwt.getClaim("sub").asString())    // Extract the 'sub' (user ID) claim.
        .build();
 
    } catch (final IncorrectClaimException e) {
    // Handle cases where the JWT's claims do not match expected values (e.g., incorrect issuer).
    
    // If the claim that caused the exception is the 'iss' (issuer) claim.
    if (StringUtils.equals(e.getClaimName(), "iss")) {
        final String message =
            e.getMessage()
                + " Be careful of the case where issuer does not match. "
                + "You have probably forgotten to set the cname in config class.";
        
        // Rethrow the IncorrectClaimException with the updated message.
        throw new IncorrectClaimException(message, e.getClaimName(), e.getClaimValue());
    }
    
    // If the exception is not related to the issuer, rethrow the original exception.
    throw e;
 
    } catch (final JwkException | JWTVerificationException e) {
    // Catch any errors related to obtaining the JWK or verifying the JWT.
    // Rethrow these exceptions as they are critical and need to be handled by the caller.
    throw e;
    }
}

Example endpoint in Spring Boot using Session Service:

  @RequestMapping("/profile")
  public String profile(
      final Model model, @CookieValue("cbo_short_session") final String cboShortSession) {
    try {
      // Validate user from token
      final SessionValidationResult validationResp =
          sdk.getSessions().getAndValidateCurrentUser(cboShortSession);
 
      // get list of emails from identifier service
      List<Identifier> emails;
      emails = sdk.getIdentifiers().listAllEmailsByUserId(validationResp.getUserID());
      model.addAttribute("PROJECT_ID", projectID);
      model.addAttribute("USER_ID", validationResp.getUserID());
      model.addAttribute("USER_NAME", validationResp.getFullName());
      // select email of your liking or list all emails
      model.addAttribute("USER_EMAIL", emails.get(0).getValue());
 
    } catch (final Exception e) {
	  //Handle verification errors here
      model.addAttribute("ERROR", e.getMessage());
      return "error";
    }
    return "profile";
  }

Providing clear unit tests for valid and invalid tokens can demonstrate how these validations work in practice. This not only ensures robustness but also offers developers a clear example of how to handle JWTs in their applications. You can take a look at SessionServiceTest as an example.

Error handling is crucial to any SDK. Some of the key exceptions in our example include:

• CorbadoServerException: Thrown when the backend API returns an HTTP status code other than 200, this exception includes deserialized error responses, making additional error information easily accessible.
• StandardException: Used for client-side errors, unrelated to the backend.
• JWTVerificationException and JwkException: Specific to session validation errors related to JWT or JWK.

The SDK also takes care of validating input on the client side to avoid sending invalid data to the server. Common validations include:

• URL validation: Ensuring that provided URLs follow the correct format.
• String constraints: For instance, ensuring that user IDs are not empty.
• Configuration validation: Certain fields, like projectId and apiSecret, should follow specific patterns (e.g., projectId starting with pro- and apiSecret starting with corbado1_).

Follow Java best practices for project structure and code quality is essential to ensure that your library is easy to use, maintain, and integrate. Below are some recommendations for structuring your SDK project and maintaining clean, readable code, with specific examples for Java.

A well-structured project is crucial for making your Java SDK standalone and easily importable by other developers. Look at this repository on GitHub, which provides sample project layouts that follow best practices. Organizing your SDK into modular components with clear directory structures helps developers navigate the code more easily and import your SDK without hassle.

To maintain clean, standardized code, it’s important to use modern formatters and linters. These tools ensure that your code adheres to established guidelines, making it more readable, consistent, and less prone to errors. Below is a recommendation for Java:

• Checkstyle with Google Java Style: Ensures your code follows Google’s Java style guidelines.
• SonarLint: Identifies potential bugs and code smells in your Java code, improving overall code quality.
• FindBugs: Detects potential issues in Java code that could lead to bugs.
• google-java-format: A tool that reformats your code according to Google’s Java style, ensuring a clean, consistent codebase.

Clean code is critical for any SDK, but it becomes even more important in smaller projects where every line of code has the potential to impact usability and maintainability.

To build a nice Java SDK, look at how established companies approach SDK development. For example, Stripe is known for having one of the most well-documented and widely used SDKs across multiple languages. Studying their approach can teach you the following:

• CI/CD Structure: Stripe uses an efficient continuous integration and continuous delivery (CI/CD) pipeline to automate tests and deployment. Understanding their setup can help you build a basic CI/CD structure that ensures your SDK is always tested and ready for production.
• What to Test in CI/CD: By observing what major SDKs like Stripe include in their test suite, you’ll learn what is critical for ensuring compatibility, such as unit tests, integration tests, and API contract validation. Testing should cover core functionality, edge cases, and backward compatibility.
• Language Version Compatibility: Ensuring compatibility with multiple versions of your target language is essential for a widely used SDK. For Java, you might support both Java 8 and above, depending on user requirements.
• Linting and Code Static Analysis: Stripe implements strict linting and code static analysis to maintain high code quality. Tools like Checkstyle for Java can be integrated into your CI pipeline to catch potential issues before they reach production.

Examining how SDKs like Stripe structure their projects can give you insights into creating a clean, modular project architecture. For example, in Java, Stripe uses the Builder Pattern for their client configuration classes, which is particularly useful when dealing with many optional parameters. This pattern ensures that your SDK’s API remains flexible while maintaining readability and simplicity for developers. If your SDK has configuration-heavy components, adopting this pattern might be ideal.

One of the key takeaways from analyzing successful SDKs is the importance of comprehensive and accessible documentation. The README file is often the first interaction a developer has with your SDK, so it should include:

• Clear setup instructions: How to install and configure the SDK with minimal friction.
• Code examples: Demonstrating core use cases, such as authentication, session handling, and error management.
• Links to further documentation: For developers who need more detailed instructions or wish to explore advanced use cases.

Are your users passkey-ready?

Test Passkey-Readiness

Building an SDK requires selecting the right libraries to ensure compatibility, maintainability, and ease of use. The stack you choose will directly affect how well your SDK integrates into other projects and how easy it is for developers to adopt it. Let’s break down the key components you’ll need to consider based on the insights gathered from previous sections and established best practices.

For Java, the two main build tools to consider are Maven and Gradle. Both are widely used, but your choice depends on the specific needs of your SDK:

• Maven: If you're more familiar with Maven and don't need custom build logic, it’s a solid, well-established option. Maven is known for its simplicity, strong dependency management, and extensive ecosystem. It integrates easily with package distribution platforms like Maven Central.

• Gradle: Gradle offers more flexibility and faster build times, especially for larger projects. It can be useful if your SDK requires more advanced build customizations or if you prioritize build performance.

Your SDK will need a reliable HTTP client to interact with APIs. For Java, consider HttpClient from the standard library or popular libraries like OkHttp if you need more flexibility.

For JSON parsing, both Jackson and Gson are widely used in Java. Jackson is often favored for its extensive features and performance, while Gson is lighter and simpler to use. If your SDK needs advanced serialization features or works with complex JSON structures, Jackson is likely the better choice.

For logging, Java developers often choose between SLF4J with Logback or Log4j. SLF4J provides an abstraction layer that allows you to switch between logging implementations without changing your code. Coupled with Logback, it offers high performance and flexibility. Log4j is another solid option but has become less popular due to past security vulnerabilities.

When handling errors, it's important to consider how your SDK will interact with external systems. For example, using a custom exception like CorbadoServerException can provide meaningful error messages when something goes wrong during API calls. This is especially useful when developers need to debug integrations with your SDK.

Testing is critical to maintaining the reliability of your SDK. For Java, tools like JUnit and Mockito are standard for unit testing and mocking. JUnit provides a simple, structured way to write tests, while Mockito allows you to mock objects in tests, which is particularly useful for API-driven SDKs where you need to simulate API responses.

Continuous integration and delivery (CI/CD) are essential for ensuring that your SDK is always deployable and free of bugs. Popular options include:

• GitHub Actions: Integrated into GitHub, making it a convenient option if your SDK is hosted there. It’s flexible, highly customizable, and free for open-source projects.
• Jenkins: A self-hosted solution that provides more control but requires additional setup and maintenance.
• Travis CI: A cloud-based CI/CD service that’s particularly popular with open-source projects.

Whichever you choose, make sure your pipeline includes automated testing, linting, and code analysis.

For Corbado's Java SDK, we used the following CI/CD process:

The SDK should be compatible with most used versions of the language. CI/CD can easily do that with matrix feature that allows you to run multiple jobs in parallel with different configurations.

This often helps identify compatibility or configuration issues that may not be apparent locally if the build or tests are failing.

Simplify the deployment process for other developers by following these steps: After build, lint and test you can choose to deploy the application on some events (for example on version tag in Java SDK). No extra steps needed. For Java, we needed to:

1. Register at Central Portal.
2. Create a GPG Key to sign the build.
3. Create a deployment job in the GitHub Actions workflow.
4. Make sure the projects comply with Central requirements.
5. Follow Centrals publishing guide for Maven
6. Configure GPG
7. Make a temporary Maven set up (needed by central publishing plugin)
8. Sign and publish the artifact

Libraries like Lombok can improve development efficiency and reduce boilerplate code. It can greatly reduce boilerplate code by automatically generating getters, setters, constructors, and builders at compile time using annotations.

Managing dependencies is a key aspect of maintaining a clean, lightweight SDK. Avoid adding unnecessary dependencies, as they can bloat your package and potentially introduce security vulnerabilities. Be mindful of separating compile-time, runtime, and test dependencies. For example, in Maven, use the <scope> tag to define when a dependency is required.

When selecting libraries, also take into account security vulnerabilities and version compatibility. For example, older versions of dependencies may no longer receive security updates, which can introduce risks to your users. Be cautious with which versions of dependencies you support and ensure that your SDK runs on the most commonly used versions of the language.

Want to find out how many people can use passkeys?

View Adoption Data

When building an SDK, ensuring a smooth and collaborative development process is key to long-term success. This requires setting up consistent configurations, automating processes where possible, and simplifying release management to make it easy for teams to work together and ship updates.

A full CI/CD pipeline is essential for ensuring that all code is automatically tested and analyzed before it reaches production. However, to make collaboration as seamless as possible, every developer working on the SDK should use the same coding standards and tools, regardless of their machine or development environment.

By sharing these configuration files through version control, developers won’t need to reconfigure their IDEs or tools every time they clone the project. This ensures consistency in code quality, reduces friction in onboarding new developers, and prevents errors caused by mismatched environments.

If possible, provide IDE-specific configuration files for your language and preferred IDEs, such as Eclipse, IntelliJ IDEA, or VS Code. This will help ensure that developers are using the same environment settings, making collaboration more efficient. For Java projects, you could include an .idea folder for IntelliJ IDEA or .project for Eclipse in your repository to share project settings.

Providing pre-configured settings files simplifies the development process by ensuring that all contributors work in an optimized and uniform environment.

Managing the SDK version should be straightforward and clear. If your versioning process is complicated or error-prone, it can lead to mistakes during release preparation, resulting in inconsistencies across different environments.

A best practice is to make the VERSION file the single source of truth for your SDK version. This simplifies the release process by ensuring that all tooling, documentation, and package metadata pull from the same version reference. By keeping the version in one place, you reduce the risk of mismatches between what’s deployed and what’s documented.

For example, you can update the VERSION file automatically during your CI/CD pipeline to reflect the latest release version. This practice can also trigger other actions, such as updating changelogs and pushing the latest version to package managers like Maven Central.

Automation plays a key role in maintaining ease of collaboration. Set up pre-commit hooks that run linters, formatters, and tests before changes are committed to the codebase. This will ensure that only clean, validated code is pushed, reducing the chance of introducing errors into the shared repository.

For example:

• Husky can be used to set up Git hooks that run scripts before code is committed.

• Prettier (for JavaScript) can automatically format code as part of the commit process, ensuring consistent styling across all commits.

Testing is a critical part of building any SDK, ensuring that it works as expected and is reliable in production environments.

When building your SDK, it’s efficient to start by referencing existing tests from similar SDKs. For example, if Corbado already has SDKs written in other languages like PHP, use those as a baseline. You can adapt and extend the existing test cases to match the language-specific features of your new SDK.

• Start by examining the key use cases covered by the existing tests, such as session validation, error handling, and JWT verification.
• Replicate those tests in your new SDK, making adjustments for language differences.
• If your SDK introduces new functionality, be sure to add additional tests that cover these features.

To ensure that your SDK delivers a great developer experience, it's essential to approach testing from the perspective of an external developer who will be using it. Set up the SDK as if you were an external user, integrating it into a sample application to identify any pain points or unclear areas.

Clear, concise, and well-structured documentation is crucial to the success of any SDK. It ensures that developers can easily understand how to implement your SDK, use its features, and troubleshoot issues. The documentation should not only provide a comprehensive overview of the SDK's capabilities but also guide developers through its use with real-world examples.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

Your documentation must clearly outline what is required for each function and configuration field. Developers need to know:

• Which arguments are required: Make it clear in the documentation which function parameters or configuration fields are mandatory and which are optional. Specify the default values for any optional parameters, if applicable.
• What constraints apply to each field: For example, is the field nullable? Are there maximum or minimum length requirements? Is the field expected to follow a certain format (e.g., email, URL)? These details should be explicitly stated to avoid confusion and potential errors during implementation.

To ensure consistency, the information in your documentation should be automatically generated from your code annotations, such as Javadoc for Java. This ensures that the documentation is always up-to-date and accurately reflects the SDK’s implementation.

Your documentation should provide detailed explanations of what each function and class does. This includes:

• The purpose of the function or class.
• What parameters it expects and their types.
• The expected output or return type.
• Any side effects the function may have (e.g., database changes, API calls).
• Specific error conditions or exceptions the user should handle.

By providing clear and descriptive documentation, you lower the barrier to entry for developers who are new to your SDK, making it easier for them to understand how to integrate it into their projects.

Beyond formal documentation, clear code comments are essential to help future developers (including your team) understand the logic behind certain code decisions. Use standard commenting practices in your codebase to:

• Explain complex logic or edge cases that might not be immediately obvious.
• Mark TODOs or areas that need further attention.
• Provide additional context when handling errors or exceptions.

Good commenting practices help bridge the gap between the code and its documentation, making the project easier to maintain and extend.

Building a Java SDK from an OpenAPI specification involves several key steps, from generating the client to ensuring ease of use for developers through proper project structure, best practices, and thorough testing. By focusing on a clean, consistent technology stack, adopting industry-standard tools and libraries, and providing robust documentation, you create an SDK that’s intuitive, reliable, and easy to integrate. Following these best practices not only streamlines development but also positions your SDK as a professional tool that developers can confidently use in production.