DEV Community: Marco Romanutti

Finally, multi-file OpenAPI specifications

Marco Romanutti — Mon, 02 Oct 2023 16:41:14 +0000

Part two of our API-first series ✨

The API-first approach prioritizes APIs over code and puts them at the beginning of the software development process.
Our previous article looked at the idea behind API-first development and some first examples. This article will focus on how OpenAPI Generator's new multiple specification files feature lets us organize our APIs.

Note: Release 7.1.0 that will fix issue 16419 and allows multiple specification files is expected to be released later this month 🔥 Until then, the feature is only supported by the CLI version.

Multiple specifications

In the real world, our APIs grow over time. Having more than one file to define all endpoints and data models can become quite messy. Therefore, we want to split our API specification into multiple files. Thankfully, the new inputSpecRootDirectory option allows us to specify a directory containing multiple OpenAPI specification files. The plugin will then merge all files into one specification and generate the code based on that.

openApiGenerate {
    generatorName.set("spring") 
    inputSpecRootDirectory.set("$rootDir/openapi")
    configFile.set("$rootDir/api-config.json")
    outputDir.set("$buildDir/generated")
}

In the last article, we created a simple API specification file user-api.yaml for a user management API. Imagine we additionally have to build an API that lists a specific order. Again, we can create an API specification file order-api.yaml.

openapi/order-api.yaml:

openapi: 3.0.0
info:
  version: 1.0.0
  title: "Order API"
  description: "API to manage orders"
paths:
  /orders/{orderId}:
    get:
      summary: Get details of a specific order by ID
      tags:
        - orders
      parameters:
        - name: orderId
          in: path
          description: "ID of the order to retrieve"
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
          description: "Unique identifier for the order."
        comment:
          type: string
          description: "Order note."
      required:
        - id
        - comment

If we again run the code generation (./gradlew openApiGenerate), we will see that the generator created a merged file referencing both specifications.

openapi/api.yaml:

openapi: "3.0.0"
paths:
  /orders:
    $ref: "./order-api.yaml#/paths/~1orders"
  /users:
    $ref: "./user-api.yaml#/paths/~1users"
info:
  title: "Merged openAPI spec"
  version: "1.0.0"

The OpenAPI specification allows us to reference external contents using the $ref attribute.
In our example ./order-api.yaml#/~1order means we

take the order-api.yaml file,
read the contents of the paths/orders node in that file (~1 escapes /, see JSON Pointer rules) and
substitute the $ref with that contents.

Don't repeat yourself

In a scenario like this, we will likely face a situation where we want to share a model between API specifications. Let's assume we want to return the user in

our user API to get the user details via /users/{userId} and in
order API to the user that placed an order via /users/{orderId}.

Again, $ref is our friend: We can define a common data model in a separate file and reference it in both API specifications.

openapi/common.yaml:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: "Unique identifier for the user."
        username:
          type: string
          description: "User's name."
      required:
        - id
        - username

Our user API references now that common data model.

openapi/user-api.yaml:

openapi: 3.0.0
info:
  version: 1.0.0
  title: "User API"
paths:
  /users/{userId}:
    get:
      summary: Get details of a specific user by ID
      tags:
        - users
      parameters:
        - name: userId
          description: "ID of the user to retrieve"
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: 'common.yaml#/components/schemas/User'

And the order API can use the shared data model, too.

openapi/order-api.yaml:

openapi: 3.0.0
info:
  version: 1.0.0
  title: "Order API"
paths:
  /users/{orderId}:
    get:
      summary: Get details of a specific user by order ID
      tags:
        - orders
      parameters:
        - name: orderId
          description: "ID of the order that placed the order"
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: 'common.yaml#/components/schemas/User'

APIs as "first-class" citizens

Using API-first to build software can benefit your organization in many ways. In this article series, we looked at what API-first means and how OpenAPI Generator can help you to adopt this approach. However, remember that more than just using and adopting the tools is required. The API-first approach requires embracing a new process - and even more crucial: Shifting from thinking in code to a code-agnostic way to design your APIs.

This article was originally posted at software-engineering-corner where Zühlke engineers write about everyday topics 🫀

Effortless API-first

Marco Romanutti — Mon, 02 Oct 2023 16:35:53 +0000

Part one of our API-first series 🛠️

The software development world is an ever-evolving landscape. Technologies and methodologies continuously evolve - each promising a more efficient and effective way to create high-quality software. One such approach that is gaining significant traction is API-first development.

In this article series, we will explore the idea behind API-first, look at practicable examples and OpenAPI Generator's new multiple specification files feature.

What does API-first mean?

API-first design is a development paradigm that prioritizes our APIs, or application programming interfaces, and how our different software pieces communicate. In this approach, APIs are designed before any line of code is written.

OpenAPI Specification is used to outline how the API should act. It is a standard that allows us to define endpoints, operations, parameters, error messages, and other information in a way that both humans and computers understand.

A fully-fledged example of an OpenAPI specification can be found here.

The benefits of API-first development

API-first comes with a lot of benefits. Here are some of them:

Better APIs: Designing an API upfront forces you to talk about the purpose of the API and how it should behave. This leads to APIs that fit their consumers' needs, are easier to use, and often reduce server and client complexity.
Development teams can work in parallel: As soon as the API specification is defined, both server and clients can start their implementation work in parallel.
Code-generation: Client and server code can be generated from the API specification.
Integration tested: Having the API defined first improves the chances that our client talks correctly to our server. Generating code and building your development and ci/cd-processes around API-first improves the chances even more.

The tools

Appropriate tooling is essential for API-first development. The following two will make our lifes easier:

Swagger Editor

The Swagger Editor is a browser-based editor where we can write OpenAPI specifications. It provides a live preview of the API documentation and allows us to generate server and client code in various languages. If you checked out the OpenAPI example before, you already have seen it in action.

OpenAPI Generator

A commonly used tool to generate code based on OpenAPI specifications is the OpenAPI Generator. It comes in different ways: As CLI, Maven plugin or Gradle plugin.

A first example

To give an example of how API-first can be used, we will create a simple API and generate the required code. This example uses version 7.0.0 of the Gradle plugin.

As described earlier, we start with designing our API. In this first step, we define an endpoint that returns the details of a specific user. The specification is written in YAML and can be found in the openapi directory.

openapi/user-api.yaml:

openapi: 3.0.0
info:
  version: 1.0.0
  title: "User API"
paths:
  /users/{userId}:
    get:
      summary: Get details of a specific user by ID
      tags:
        - users
      parameters:
        - name: userId
          in: path
          description: "ID of the user to retrieve"
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: "Unique identifier for the user."
        username:
          type: string
          description: "User's name."
      required:
        - id
        - username

The specification consists of the following elements:

openapi: Defines the version of the OpenAPI specification being used.
info: Version, name and a brief description of the API.
paths: Exposes all available endpoints - in our case a GET endpoint to retrieve user details, including supported operations, parameters and possible responses.
components: Used to define reusable data models. Currently, we only have a User object.

So far, so clear.

Having our OpenAPI specification, we can now generate the required code. To do so, we need to add the following plugin to our build.gradle.kts file:

plugins {
    id("org.openapi.generator") version "7.0.0"
}

Generating the server

The plugin now allows us to specify further how the code should be generated. We want to generate a Spring server in this example. Therefore, we need to add the following task to our build.gradle.kts file:

openApiGenerate {
    generatorName.set("spring")
    inputSpec.set("$rootDir/openapi/user-api.yaml")
    configFile.set("$rootDir/api-config.json")
    outputDir.set("$buildDir/generated")
}

Let's see what we configured:

generatorName specifies the generator to use.
inputSpec contains the OpenAPI specification we use to generate our code.
configFile allows to customize further the code generation (check out the docs to learn more about the available options).
outputDir specifies the directory where the generated code should be placed.

We are now ready to run the code generation. To do so, we can run the following command:

./gradlew openApiGenerate

This will result in an interface that can be implemented in the respective controller on sever side.

@Generated
public interface UsersApi {

    @Operation(
            operationId = "usersUserIdGet",
            summary = "Get details of a specific user by ID",
            responses = {
                    @ApiResponse(responseCode = "200", description = "OK", content = {
                            @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))
                    })
            }
    )
    @RequestMapping(
            method = RequestMethod.GET,
            value = "/users/{userId}",
            produces = {"application/json"}
    )
    default ResponseEntity<User> usersUserIdGet(
            @Parameter(name = "userId", description = "ID of the user to retrieve", required = true, in = ParameterIn.PATH) @PathVariable("userId") Integer userId
    ) {
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
    }
}

And also, the data transfer object (DTO) that is returned by the server was generated:

@Generated
public class User {

  private Integer id;

  private String username;

  public User(Integer id, String username) {
    this.id = id;
    this.username = username;
  }

  public User id(Integer id) {
    this.id = id;
    return this;
  }

  @NotNull 
  @Schema(name = "id", description = "Unique identifier for the user.", requiredMode = Schema.RequiredMode.REQUIRED)
  @JsonProperty("id")
  public Integer getId() {
    return id;
  }

  public void setId(Integer id) {
    this.id = id;
  }

  public User username(String username) {
    this.username = username;
    return this;
  }

  @NotNull 
  @Schema(name = "username", description = "User's name.", requiredMode = Schema.RequiredMode.REQUIRED)
  @JsonProperty("username")
  public String getUsername() {
    return username;
  }

  public void setUsername(String username) {
    this.username = username;
  }
}

Generating the client

Just as we generated server code, we can also generate client code using an appropriate generator. In our case, we want to generate a TypeScript client. Therefore, we choose the typescript-angular generator in our gradle task:

openApiGenerate {
    generatorName.set("typescript-angular")
    inputSpec.set("$rootDir/openapi/user-api.yaml")
    configFile.set("$rootDir/api-config.json")
    outputDir.set("$buildDir/generated")
}

The generator will generate a service that can be used to call the API (generated services are quite verbose - for clarity, we focus on the relevant parts):

@Injectable({
    providedIn: 'root'
})
export class UsersService {

    constructor(protected httpClient: HttpClient) {
        // ...
    }

    public usersUserIdGet(userId: number): Observable<User> {
        // ...
    }
}

As the client code in our case includes the fully-fledged implementation of the service, we can directly use it in our application.

Also, a corresponding data transfer object was generated:

export interface User {
    id: number;
    username: string;
}

A final thought about organizing your code: Keep your generated code in a separate directory or module to keep it isolated from your application code. This will make managing and updating your generated code easier as your API evolves over time.

Conclusion

As we can see, the OpenAPI Generator is a powerful tool that can be used to generate code for both server and client side. In the next article we will look at a more realistic example and how OpenAPI Generator helps you to keep your specification files structured.

This article was originally posted at software-engineering-corner where Zühlke engineers write about everyday topics 🫀

Avoid the urgency trap

Marco Romanutti — Tue, 01 Nov 2022 20:17:25 +0000

Or: Why architecture matters in software projects

A software project generally has different stakeholders.

One obvious stakeholder is the customer. They commission software developers to build software that meets certain requirements. The customer's focus often lies on the behavior of the software: It should behave in a way that makes or saves money for the customer. Many software engineers consider this their main task. They believe their job is to implement functionality to meet businesses' requirements.

However, this ignores that developers are their software's stakeholders too. Software contains the term soft. It is intended to be soft: Changing software and their behavior should be easy - otherwise, we would have called it hard*ware. When the business changes a requirement or aims for a new feature, that change should be easily accomplishable. We use **architecture* to structure our applications to minimize the efforts required to build and maintain a system. Because architectural aspects often require a technical understanding of the system, it is the task of the developer (and architect) to ensure architecture in a software project.

Both, implementing the behavior of the software and enforcing its architectural aspects require resources. As time and money are limited in software projects (at least those of which I have been a part), we ask ourselves which one to prioritize.

The Mere-Urgency Effect a.k.a. Why We're Bad at Prioritization

Already President Dwight D. Eisenhower recognized that we have difficulties answering that question. At the 1961 Century Association, he stated:

Who can define for us with accuracy the difference between the long and short term! Especially whenever our affairs seem to be in crisis, we are almost compelled to give our first attention to the urgent present rather than to the important future.

This observation was recently confirmed by a study in the Journal of Consumer Research. Researchers examined how people decide what to work on when faced with tasks of mixed urgency and importance. Across five experiments, they observed the following pattern:
We tend to favor time-sensitive tasks over tasks that are less urgent, regardless of their long-term payoffs. This psychological quirk is called the Mere-Urgency Effect.

The Long-Term View

In software projects, the software's behavior is usually urgent: If you ask the business managers, they'll say it's essential for the software to work. But this view can be challenged by examining the extremes. Look at the following example:

If you develop an application that works perfectly but is impossible to change, then it won't work when the requirements change. The application will become useless.

If you develop an application that does not work but is easy to change, then you can easily make the application work - and keep it working when the requirements change. The application will remain useful.

It's a software developer's dilemma that the customer often can not evaluate the importance of architecture. As a software developer we are stakeholders as well. It's in our responsibility and also in our interest to ensure architecture in software projects. If we neglect architecture, our applications will become cumbersome, changes will become expensive and we might end up in a non-operatable state.

This article was originally posted at software-engineering-corner where Zühlke engineers write about everyday topics 🫀