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