LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-09 20:57:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

1534-review-guide-for-replacing-servers (#1542)

Browse Source 
* Removed header numbering, removed "We do" admonition, improved language for consistency.

* Cleaned up markdownlint and vale errors

* Cleaned up markdown

* Ran Prettier

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: Revert changes to package files

* Update docs/guides/replace-servers-url.md

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

* Update replace-servers-url.md

Included changes from comments

* Extended intro, added subheadings to "Verify the output", added a summary and resources

* docs: Prettier being fussy

---------

Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>
Co-authored-by: Heather Cloward <heathercloward@gmail.com>
Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>
This commit is contained in:
JLekawa
2024-05-09 11:59:59 +02:00
committed by GitHub
parent 875dfa8d8b
commit e2b59a0dfc
1 changed files with 74 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/guides/replace-servers-url.md
View File

@@ -2,13 +2,13 @@
Redocly allows you to use [custom decorators](../custom-plugins/custom-decorators.md) to modify content in the API description during the bundling process.
You can use this method to create multiple instances of an API description file from a single source, each with a different server. For example, you can have separate API descriptions configured with your mock server and your production server, or separate API files for each of your customers.
This page describes how to replace the server URL with a decorator for a given environment.
## Prerequisites
{% admonition type="note" name="We do, You do" %}
This tutorial is most effective when you follow along and complete the steps.
{% /admonition %}
- [Install @redocly/cli](../installation.md). We use version 1.12.0 in this tutorial.
- [Install @redocly/cli](../installation.md) with version 1.0.0-beta.111 or later (we use 1.0.0-beta.111 in this tutorial).
- Save the following OpenAPI file as `original.yaml` into a new directory named `replace-servers-demo`.
@@ -34,13 +34,44 @@ This tutorial is most effective when you follow along and complete the steps.
```
- Use your favorite IDE for editing files (we use VS Code and have the [Redocly extension](https://redocly.com/docs/redocly-openapi/) installed).
## Step 1: Create a custom plugin
## Create a demo folder and description file
Before you start, create a demo folder and a sample OpenAPI description file to later test your plugin and decorators.
1. Create a new folder and name it `replace-servers-demo`.
2. In the `replace-servers-demo` folder, create an `original.yaml` file with the following content:
```yaml
openapi: 3.1.0
info:
version: 1.0.0
title: Custom decorators demo
description: The servers URL is replaced by the decorator during the `bundle` process.
servers:
- url: 'https://example.com/api/v1'
paths:
/status:
get:
summary: Get status
operationId: getStatus
security: []
responses:
'204':
description: Status OK
'400':
description: Status not OK
```
3. Save the file.
## Create a custom plugin
In this step, create a custom plugin and define the decorator dependency.
1. Create a directory called `plugins`.
1. In the `replace-servers-demo` folder, create a folder called `plugins`.
2. Create a `plugin.js` file inside of the `plugins` directory with this information.
2. In the `plugins` folder, create a `plugin.js` file with this code:
```JavaScript
const ReplaceServersURL = require('./decorators/replace-servers-url');
@@ -62,15 +93,16 @@ module.exports = {
3. Save the file.
{% admonition type="attention" %}
You can name the plugins directory and file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3).
If you change the names of the plugins directory or the files, make sure to change them also in the Redocly configuration file [when registering your plugins and decorators](#add-a-decorator-and-associate-it-with-an-environment-variable).
{% /admonition %}
## Step 2: Add a decorator and associate it with an environment variable
## Add a decorator and associate it with an environment variable
In this step, add a decorator and define the environment variable associated with it.
1. Create a directory `decorators` inside of the `plugins` directory.
1. Create a `replace-servers-url.js` file with this information and save it inside of the `decorators` directory.
1. Inside the `plugins` folder, create a `decorators` folder.
2. In the `decorators` folder, create a `replace-servers-url.js` file with this code:
```JavaScript
module.exports = ReplaceServersURL;
@@ -92,13 +124,17 @@ function ReplaceServersURL({serverUrl}) {
};
```
3. Save the file.
{% admonition type="attention" %}
You can name the decorators directory anything you want. Make sure you use the correct directory name in line 1 of the `plugin.js` file (Step 1).
If you change the name of the decorators directory, make sure to also change it in line 1 of the [`plugin.js` file](#create-a-custom-plugin).
{% /admonition %}
## Step 3: Configure the plugin for use
## Configure the plugin for use
To use the decorator, register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`.
To use the decorators, register your `plugins` and `decorators` in the [Redocly configuration file](../configuration/index.md).
- In your Redocly configuration file, register your plugins and decorators:
```yaml
apis:
@@ -118,15 +154,17 @@ extends:
- recommended
```
## Step 4: Verify the output
## Verify the output
The following command bundles the `original.yaml` API with the "backend" server URL.
### Check the configuration for the "backend" server
```yaml
1. Run the following command to bundle the `original.yaml` API with the "backend" server URL.
```shell
npx @redocly/cli bundle sample@v1-backend
```
The output should show the correct server URL.
2. Verify that the output shows the correct server URL.
```yaml
openapi: 3.1.0
@@ -139,13 +177,15 @@ servers:
# ...
```
The following command bundles the `original.yaml` API with the "proxy" server URL.
### Check the configuration for the "proxy" server
```yaml
1. Run the following command bundles the `original.yaml` API with the "proxy" server URL.
```shell
npx @redocly/cli bundle sample@v1-proxy
```
The output should show the correct server URL.
2. Verify that the output shows the correct server URL.
```yaml
openapi: 3.1.0
@@ -157,3 +197,17 @@ servers:
- url: https://proxy.example.com/v1
# ...
```
## Summary
In this tutorial you have created a plugin and a decorator that replace the server URL with one of the URLs defined in the Redocly configuration file.
You now have two API description files, each configured to send requests to different servers.
## What's next?
You can reuse the code from your demo files and modify it to fit your API documentation.
For more custom plugins, configuration, and other resources, see the [Redocly CLI Cookbook](https://github.com/Redocly/redocly-cli-cookbook).
For the latest Redocly news and articles, visit our [blog](https://redocly.com/blog/).