paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity

Merge pull request #26901 from AmbrishRamachandiran/openapi-grammer

Browse Source 
Fixed grammar mistakes in openapi-docs
This commit is contained in:
Camila Belo
2024-10-15 10:21:59 +02:00
committed by GitHub
parent 2bdc056536 8bbb568d46
commit cd7347ef3d
1 changed files with 6 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openapi/01-getting-started.md
+6 -6
View File
@@ -14,8 +14,8 @@ Difficulty: Medium
The goal of this tutorial is to give you exposure to tools that more tightly couple your OpenAPI specification and plugin lifecycle. The tools we'll be presenting were created by the OpenAPI tooling project area and allow you to create,
1. A typed `express` router that provides strong guardrails during development for input and output values. Support for query, path parameters and request body, as well as experimental support for headers and cookies.
2. An auto-generated client to interact with your plugin's backend. Support for all request types, parameters and body, as well as return types. Provides a low-level interface to allow more customization by higher level libraries.
1. A typed `express` router that provides strong guardrails during development for input and output values. Support for query, path parameters, and request body, as well as experimental support for headers and cookies.
2. An auto-generated client to interact with your plugin's backend. Support for all request types, parameters, and body, as well as return types. Provides a low-level interface to allow more customization by higher-level libraries.
3. Validation and verification tooling to ensure your API and specification stay in sync. Includes testing against your unit tests.
## Prerequisites
@@ -32,8 +32,8 @@ This tutorial assumes that you're already familiar with the following,
There are two required npm packages before we start,
1. `@backstage/repo-tools`, this package contains all OpenAPI related commands for your plugins. We will be using this throughout the tutorial.
2. `@useoptic/optic`, this package is a dependency of `@backstage/repo-tools` but is only required for OpenAPI related commands.
1. `@backstage/repo-tools`, this package contains all OpenAPI-related commands for your plugins. We will be using this throughout the tutorial.
2. `@useoptic/optic`, this package is a dependency of `@backstage/repo-tools` but is only required for OpenAPI-related commands.
Further, for generating the client a `java` binary has to be available on your PATH.
@@ -47,7 +47,7 @@ You should create a new folder, `src/schema` in your backend plugin to store you
## Generating a typed express router from a spec
Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use and you can combine both the server generation and the client generation below like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package <clientPackageDirectory>`
Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use, and you can combine both the server generation and the client generation below, like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package <clientPackageDirectory>`
Use it like so, update your `router.ts` or `createRouter.ts` file with the following content,
@@ -86,7 +86,7 @@ export class CatalogClient implements CatalogApi {
usage of the types will depend on your type names.
You should be able to use the generated `DefaultApi.client.ts` file out of the box for your API needs. For full customization, you can use a wrapper around the generated client to adjust the flavor of your clients.
You should be able to use the generated `DefaultApi.client.ts` file out of the box for your API needs. For full customization, you can use a wrapper around the generated client to adjust the flavour of your clients.
For more information, see [the docs](./generate-client.md).