API first services with Spring Boot

No Comments

In several posts, I’ve touched on the API first paradigm. I would now like to review the basic statements of API first before we take a look at the concrete implementation.

API first recap

The API first approach is about a product-centric mindset and the understanding that development is never finished and the customer is fundamentally the focus of every iteration. Likewise, the technology behind the specification does not play a leading role. Furthermore, it is about parallelism in an already accelerated software development. The goal is to create a system in which users can effortlessly obtain information and build applications based on it.

The implementation

In the role of an API producer, I would like to try to implement a service drawing on the idea of API first. Specifically, I want to create a Spring Boot service that will deliver a list of news items via an API with the endpoint /api/news.

At the beginning, the focus is on creating the OpenAPI specification. It is the starting point for any code generated later. The specification is kept very simple and is presented as follows:

openapi: 3.0.3
  - url: 'http://localhost:8080/api'
  version: 1.0.0
  title: News API
    name: Daniel Kocot
    url: 'http://www.codecentric.de'
    email: daniel.kocot@codecentric.de
    name: MIT
    url: https://www.tldrelgal.com/mit
  description: An API to provide news
  - name: news
      description: gets latest news
      operationId: getNews
        - news
          description: Expected response to a valid request
                $ref: '#/components/schemas/ArticleList'
              examples: {}
          description: Unexpected error
                $ref: '#/components/schemas/Error'
      title: ArticleList
      type: array
        $ref: '#/components/schemas/Article'
      title: Article
      description: A article is a part of a news.
      type: object
          type: integer
          type: string
          type: string
          format: date
          type: string
          type: string
        - id
        - title
        - date
        - description
        - imageUrl
        type: object
            type: string
            type: string
          - code
          - message
  securitySchemes: {}
        description: Example shared example
        type: object
            type: string
          - id

The specification was created using Stoplight Studio and is based on OpenAPI version 3.0.3. Stoplight Studio offers integration with GitHub, making it easier to version the models and specifications. In the GitHub repo itself, there is also a GitHub action configured that checks the specifications via spectral linter on pushes to the main branch or pull requests on it. In order not to blow up the blogpost, we will fall back on the built-in ruleset for Spectral. Spectral is also used as a linter in Stoplight Studio at the same time.
After the OpenAPI Spec is available, a service can be built based on Spring Boot and Gradle. The gradle.build file looks like this:

plugins {
    id 'org.springframework.boot' version '2.5.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'de.undercouch.download' version '4.1.2'
    id 'io.openapiprocessor.openapi-processor' version '2021.3'
    id 'java'

group = 'de.codecentric'
version = '0.0.2-SNAPSHOT'
sourceCompatibility = '11'

repositories {

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-data-rest'
    implementation 'org.springframework.boot:spring-boot-starter-web'

    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    runtimeOnly 'com.h2database:h2'

    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

test {

task downloadFile(type: Download) {
    src "https://raw.githubusercontent.com/codecentric/api-showcases/main/specs/news.yaml"
    dest "${projectDir}/src/api"
    onlyIfModified true
    useETag true

openapiProcessor {
    spring {
        processor 'io.openapiprocessor:openapi-processor-spring:2021.5'
        apiPath "$projectDir/src/api/news.yaml"
        targetDir "$projectDir/build/openapi"
        mapping "$projectDir/mapping.yaml"
        showWarnings true

afterEvaluate {

sourceSets {
    main {
        java {
            srcDir "build/openapi"

    test {
        resources {
            srcDir file('src/test/java')
            exclude '**/*.java'


springBoot {
    mainClassName = "de.codecentric.apifirstspringboot.ApifirstSpringbootApplication"

Two plug-ins are needed to generate the model and interfaces of the API. Because the specification is located in a repository on GitHub, a download task is required. This is provided by the plug-in from Michel Krämer. For the actual generation step, OpenAPI Processor is used instead of OpenAPI Generator. OpenAPI Processor is a fairly lightweight framework that converts the OpenAPI YAML file into a target format to be selected. Besides the plug-in for Gradle, there is also one available for Maven. Currently there are so-called processors for the following target formats:

  • Spring
  • Micronaut
  • JSON

The conversion of the OpenAPI spec is configured by using a mapping.yaml. For this post only a simple configuration is used.

openapi-processor-mapping: v2

  package-name: de.codecentric.generated.news

  result: org.springframework.http.ResponseEntity

    - type: array => java.util.List

To start the conversion for the first time, gradle clean compileJava is sufficient. Now the models and the interface are available in the package de.codecentric.generated.news. To avoid accessing the API model of the article entity directly, it is recommended to create a separate entity. It is also possible that the entity does not correspond exactly to the API model. In the example, the Article entity contains another attribute Author, which is not provided to the outside via API. To create a mapping between the entity and the model, a corresponding mapper class is created.

package de.codecentric.apifirstspringboot.mapper;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import de.codecentric.apifirstspringboot.entities.Article;

import java.util.List;
import java.util.stream.Collectors;

public class ArticleModelMapper {

    private static ObjectMapper objectMapper = new ObjectMapper();

    public static Article toEntity(de.codecentric.news.api.model.Article article) {
        return Article.builder()

    public static de.codecentric.news.api.model.Article toApi(Article article) {
        de.codecentric.news.api.model.Article articleModel = new de.codecentric.news.api.model.Article();

        return articleModel;

    public static List<de.codecentric.news.api.model.Article> toApi(List<Article> retrieveAllArticles) {
        return retrieveAllArticles.stream()

    public static de.codecentric.news.api.model.Article jsonToArticle(String json) throws JsonProcessingException {
        return objectMapper.readValue(json, de.codecentric.news.api.model.Article.class);

A framework such as Mapstruct can also be used for mapping.
In order to make an API available to the outside world via the service, a repository class and a controller class are required.

package de.codecentric.apifirstspringboot.repository;

import de.codecentric.apifirstspringboot.entities.Article;
import org.springframework.data.jpa.repository.JpaRepository;

public interface NewsRepository extends JpaRepository<Article, Long> {


The controller will implement the generated API interface.

package de.codecentric.apifirstspringboot.controller;

import de.codecentric.apifirstspringboot.service.NewsService;
import de.codecentric.generated.news.api.NewsApi;
import de.codecentric.generated.news.model.Article;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import java.util.List;

import static de.codecentric.apifirstspringboot.mapper.ArticleModelMapper.toApi;

public class NewsController implements NewsApi {

    private NewsService newsService;

    public NewsController(NewsService newsService) {
        this.newsService = newsService;

    public ResponseEntity<List<Article>> getNews() {
        List<de.codecentric.apifirstspringboot.entities.Article> allArticles = newsService.retrieveAllArticles();
        return ResponseEntity.ok().body(toApi(allArticles));

Based on schema.sql and data.sql, the /api/news endpoint returns the following JSON response.

        "date": "2021-07-08",
        "description": "codecentric is...",
        "id": 1,
        "imageUrl": "http://picserve.codecentric.de/1/bild",
        "title": "Company news"

Pitfalls: OpenAPI spec

Finally, I would like to mention two pitfalls that came up during the development. First of all, you should have noticed that the latest OpenAPI specification is not used. This is due to the fact that the parsers in the Java environment (swagger and openapi4j) only support OpenAPI Spec 3.0 (more precisely 3.0.3). This then affects other code generators, such as the OpenAPI generator.
If you decide to develop based on API first, it is important to keep an eye on which version of the specification is already supported by the generators.
In the OpenAPI spec, the URL of the server also contains the base path (/api). The servers.url field is not read by the OpenAPI Processor. There are now two possible solutions. Either the base path is always stored in the paths or it must be manually stored in the controller for the API as an annotation. The second variant can be found in the repo.


We can see that it is possible, with limitations, to develop services with Spring Boot based on the idea of API first. If one is also aware of the current pitfalls, it will be possible to make services available with the appropriate speed and quality.

Daniel has been part of the codecentric team since October 2016. Since the beginning of 2022 he works as Senior Solution Architect at the Dortmund branch. Starting as a consultant with a focus on application lifecycle management, his focus shifted more and more towards APIs. In addition to numerous customer projects and his involvement in the open source world around APIs, our Head of API Experience & Operations is also a frequent speaker at conferences.


Your email address will not be published.