Also available in German at miragon.io
With each new backend release a frontend developer has to rewrite huge parts of the API client. What if there would be a solution to update the whole client in just a few seconds?
In this blog post, we're introducing Swagger’s client generation, showing how to use the generated API in React applications and pointing out how to integrate Auth0's authentication token.
To keep things simple, this topic will be divided into a series consisting of three parts:
- Generating Client APIs using Swagger Part 1: Integrating Swagger into Spring Boot, generating the API client and using it as part of a React web app
- Generating Client APIs using Swagger Part 2: Securing the endpoints using Auth0 and authorising the web client’s requests
- Generating Client APIs using Swagger Part 3: Using the generated API client as part of a React Native App.
Integrating Swagger in Spring Boot and generating the client
The goal of this section is to generate the API documentation of a Java Spring Boot application using Swagger, create the according TypeScript Axios Client, which encapsulates the API calls, and integrate this client into a React web app. The result will look like this:
tl;dr
- Clone our example-backend, start Docker and run the application using the Spring Boot
no-security
profile. - Clone our example-webapp, install all dependencies using
yarn install
and runyarn generate-api
in the project’s root
Step 1) Integrate Swagger into Spring Boot
All code snippets are part of our example-backend. This backend application allows managing projects, which represent an object containing the customer’s name and their address. Using the API endpoints, a client is able to create, read, update, and delete (CRUD) projects.
1a) Annotate the controllers and add information about each endpoint
After adding the springdoc-openapi-ui
dependency to the dependency management file (e.g. build.gradle
or pom.xml
), you’ll be able use its annotations for the projects controllers.
@Slf4j
@Validated
@RestController
@RequiredArgsConstructor
@Tag(name = "Project Controller")
@RequestMapping("/api/project")
public class ProjectController {
private final ProjectService projectService;
private final ProjectApiMapper projectMapper;
@Transactional(readOnly = true)
@GetMapping
@Operation(summary = "Get list of all projects")
public ResponseEntity<List<ProjectTO>> getAllProject() {
log.debug("Received request to load all projects");
final List<Project> allProjects = this.projectService.getAllProjects();
return ResponseEntity.ok(this.projectMapper.mapToTO(allProjects));
}...
1b) Visit the generated API documentation
- As described in the project’s
README
, both Docker services (nginx
andpostgres
) have to run until you can start the example backend. - Please make sure that you’ve enabled the
no-security
profile in the run configurations:
IntelliJ → Run → Edit Configurations… → Active profiles:no-security
- Now you should be able open the API documentation in your browser:
http://localhost:8081/swagger-ui.html
Step 2) Generate the API Client
There are several ways to generate an API client using Swagger: You could use a Gradle or Maven plugin, use Swagger Editor or use a third-party JavaScript library. In our opinion, generating the client API should not be part of the backend. That’s why we went with the Swagger Editor in the first place and later switched to the openapi-generator-cli
later on to have the benefit of strongly typed interfaces. In this section, we’ll explain both ways, using Swagger Editor and openapi-generator-cli
:
a) Swagger Editor
- Open the URL
http://localhost:8081/v3/api-docs
and copy everything. - Visit Swagger Editor (https://editor.swagger.io/) and paste it into the editor window → you will be asked if you want to convert it to .yaml → Accept.
- In the menu of Swagger Editor, you’ll find the “Generate Client” dropdown. Select “TypeScript Axios”, and wait until the download has finished.
- Unzip it, copy
api.ts
,base.ts
,configuration.ts
,apis-folder
, andmodels-folder
into a new folder in your frontend project.
b) Openapi-Generator-Cli
- Download and add
@openapitools/openapi-generator-cli
as dev-dependency in your webapp using the following command:yarn add --dev @openapitools/openapi-generator-cli
- Make sure that your backend is up and running.
- Run the following command:
yarn openapi-generator-cli generate \
-i http://localhost:8081/v3/api-docs \
-g typescript-axios \
-o src/api
Optional: Delete the files .npmignore
, .gitignore
, and git_push.sh
, and add them to the file .openapi-generator-igonre
. Add openapitools.json
, and /src/api/.openapi-generator
to your project’s .gitignore
.
Step 3) Using the API Client in a React Web Application
To work with the generated API using an nginx
as reverse proxy, you first have to set the BASE_PATH
variable in src/api/base.ts
to an empty string:
export const BASE_PATH = "";
Now you can fetch data from the API endpoint with just three lines of code:
const projectController = new ProjectControllerApi()
const response = await projectController.getAllProject()
const data = response.data
In our example-webapp, we encapsulated the all api-calls within a helper method to catch the errors. Additionally we’re using redux-store
to cache the received data, which allows us to reduce the backend calls.
In the next part of this series, we will see how to secure the endpoints using Auth0 and authorize the web client’s requests. Stay tuned for part 2!