Internal Developer Platforms – Part 12: Backstage Entities and OpenAPI Example

In the last blog post, we discussed the various entity types within Backstage’s Software Catalog. As the plain theory is sometimes quite abstract, we will continue with an concrete example and show how to publish the API of a simple Java Spring REST service in Backstage and publish its API in the OpenAPI specification format within Backstage.

The sample app

As we are using Spring Boot, we can simply create a simple application with Spring Initializr. We open the page https://start.spring.io and can provide the input as shown in the screenshot below:

Once unpacked we can write some simple logic for the RestController.

package cloud.sclabs.backstage.sampleapp;

import java.util.List;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
class EmployeeController {

  @GetMapping("/employees")
  List<String> all() {
    …;
  }
  
  @GetMapping("/employees/{id}")
  Employee one(@PathVariable Long id) {
    
    …
  }

  @PutMapping("/employees/{id}")
  Employee replaceEmployee(@RequestBody Employee newEmployee, @PathVariable Long id) {
    
    …
  }

  @DeleteMapping("/employees/{id}")
  void deleteEmployee(@PathVariable Long id) {
    …
  }
}

In order to create the OPEN API documentation, we simply add the following dependency on the classpath:

<dependency>
<groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.5.0</version>
</dependency>

Once we have built and started our application (./mvnw clean spring-boot:run) , we can see the documentation when opening the following URL: http://localhost:8080/swagger-ui/index.html

Backstage Entities

Now it is time to write some YAML for the Backstage entities. We create a backstage folder within the repository and add the following directories and files (mkdocs will be explained within the next blog post):

Let’s take a look into the yaml files. Our entry point is the all.yaml:

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: backstage-sample-app
  description: A collection of all Backstage entities
spec:
  targets:
    - ./all-apis.yaml
    - ./all-components.yaml

---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: backstage-sample-app
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: gsoeldner/backstage-sample-app
spec:
  owner: user:default/guido.soeldner

Within the YAML, we define a location and load the all-apis.yaml and the all-components.yaml.

The location entity all-apis.yaml covers the different APIs – in our case just simple one:

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: event-sourcing-poc-apis

  description: A collection of all Backstage event-sourcing-poc APIs
spec:
  targets:
    - ./apis/employees-api.yaml

Finally, we have the employees-api.yaml:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: employees-api
  description: The employees API
  tags:
    - employees
    - query
    - rest
  links:
    - url: https://github.com/gsoeldner-sc/backstage-sample-app
      title: Server Root
      icon: github
spec:
  type: openapi
  lifecycle: experimental
  owner: user:default/guido.soeldner
  definition: |
	SPEC from Spring APP

The last line covers the Spring App OpenAI spec. The most easy way is to retrieve the API as JSON (http://localhost:8080/v3/api-docs) and replace the line in the sample.

Of course we also need to define the components:

apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: event-sourcing-poc-components
  description: A collection of all Backstage event-sourcing-poc components
spec:
  targets:
    - ./components/employees-component.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: employees-component
  description: command side of order aggregate
  annotations:

    backstage.io/source-location: url:https://github.com/gsoeldner-sc/backstage-sample-app
  links:
    - url: https://github.com/gsoeldner-sc/backstage-sample-app
      title: Server Root
      icon: github
spec:
  type: service
  lifecycle: experimental
  system: examples
  owner: user:default/guido.soeldner
  providesApis:
    - employees-api

Once, everything is done, we can easily import the definitions into the Software Catalog.

Once done, we can easily browse all the APIs, similar like if you go to some kind of Developer Pages like the Google API docs.

> Click here for Part 13: Working with Backstage TechDocs