diff --git a/docs-end-user.sidebars.yaml b/docs-end-user.sidebars.yaml index bd0f7107..6f1a6383 100644 --- a/docs-end-user.sidebars.yaml +++ b/docs-end-user.sidebars.yaml @@ -15,5 +15,9 @@ label: Interact with walkthroughs - page: docs/end-user/interact-with-api.md label: Interact with API documentation +- page: docs/end-user/test-apis-replay.md + label: Test APIs using Replay +- page: docs/end-user/test-apis-cli.md + label: Test APIs using CLI - page: docs/end-user/user-menu.md label: User menu \ No newline at end of file diff --git a/docs/end-user/index.md b/docs/end-user/index.md index ed3ae5f9..5ed0f003 100644 --- a/docs/end-user/index.md +++ b/docs/end-user/index.md @@ -10,7 +10,8 @@ Explore the following pages to learn more about the projects' user interface: - [Search a project](./use-search.md) - [Interact with pages](./interact-with-pages.md) - [Interact with API documentation](./interact-with-api.md) -- [Test APIs using Replay](./test-apis.md) +- [Test APIs using Replay](./test-apis-replay.md) +- [Test APIs using CLI](./test-apis-cli.md) - [Use a classic catalog](./use-classic-catalog.md) - [Interact with walkthroughs](./interact-with-walkthroughs.md) - [User menu](./user-menu.md) diff --git a/docs/end-user/interact-with-api.md b/docs/end-user/interact-with-api.md index 0a8c5596..8c9209c8 100644 --- a/docs/end-user/interact-with-api.md +++ b/docs/end-user/interact-with-api.md @@ -107,5 +107,6 @@ After you click **Send**, your feedback is submitted. - [Use a classic catalog](./use-classic-catalog.md) - [Interact with pages](./interact-with-pages.md) -- [Test APIs using Replay](./test-apis.md) +- [Test APIs using Replay](./test-apis-replay.md) +- [Test APIs using CLI](./test-apis-cli.md) - Explore other ways you can interact with the [user interface](./index.md) diff --git a/docs/end-user/interact-with-pages.md b/docs/end-user/interact-with-pages.md index d9447616..4e5ebcad 100644 --- a/docs/end-user/interact-with-pages.md +++ b/docs/end-user/interact-with-pages.md @@ -68,5 +68,6 @@ Your message is sent to the organization that owns the project. - [Interact with walkthroughs](./interact-with-walkthroughs.md) - [Interact with API documentation](./interact-with-api.md) +- [Test APIs using CLI](./test-apis-cli.md) - [Use a classic catalog](./use-classic-catalog.md) - Explore other ways you can interact with the [user interface](./index.md) diff --git a/docs/end-user/test-apis-cli.md b/docs/end-user/test-apis-cli.md new file mode 100644 index 00000000..155663cf --- /dev/null +++ b/docs/end-user/test-apis-cli.md @@ -0,0 +1,96 @@ +# Test APIs using CLI + +Use the curl app in a command-line interface (CLI) tool of your choice to make calls to APIs in your project. + +You can send requests to servers listed on API documentation page, or to Redocly mock server. + +## Use curl to call an API operation + +To send an API request using curl: + +1. Go to the API documentation page for the operation you want to call. +1. Copy the curl command from the code samples. +1. (Optional) To change the server, scroll to the **Servers** section of the API documentation page, click the **Copy** icon next to a server URL, and paste the value into your command. +1. Update the values in the curl command as needed. + + For example: + + ```curl {% title="curl command to call Update special event operation" %} + curl -i -X PATCH \ + -u : \ + 'https://redocly.com/_mock/docs/openapi/museum-api/special-events/dad4bce8-f5cb-4078-a211-995864315e39' \ + -H 'Content-Type: application/json' \ + -d '{ + "location": "Under the sea." + }' + ``` +1. Run the curl command in a CLI tool. + +The CLI tool outputs a response from the server. + +```bash curl {% title="mock server response" %} +HTTP/2 200 +access-control-allow-credentials: true +access-control-allow-headers: * +access-control-allow-methods: * +access-control-allow-origin: * +alt-svc: h3=":443"; ma=2592000 +content-type: application/json +date: Thu, 11 Jul 2024 17:24:24 GMT +server: Caddy +strict-transport-security: max-age=31536000; +x-content-type-options: nosniff +x-frame-options: deny +x-xss-protection: 1;mode=block; + +{"eventId":"dad4bce8-f5cb-4078-a211-995864315e39","name":"Mermaid Treasure Identification and Analysis","location":"Under the sea.","eventDescription":"Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.","dates":["2023-09-05","2023-09-08"],"price":15}% +``` + +## Return a specific response example + +Force the Redocly mock server to respond with a specific example from the API description using the `x-redocly-response-body-example` header to pass the example's name. + +The following example forces a response for a `general_entry` ticket from the Museum API's mock server: + +```curl +curl -i -X POST \ + -u : \ + https://redocly.com/_mock/docs/openapi/museum-api/tickets \ + -H 'x-redocly-response-body-example: general_entry' \ + -H 'Content-Type: application/json' \ + -d '{ + "ticketType": "event", + "eventId": "dad4bce8-f5cb-4078-a211-995864315e39", + "ticketDate": "2023-09-05", + "email": "dave@example.com" + }' +``` + +The following example forces a response for an `event_entry` ticket from the Museum API's mock server: + +```curl +curl -i -X POST \ + -u : \ + https://redocly.com/_mock/docs/openapi/museum-api/tickets \ + -H 'x-redocly-response-body-example: event_entry' \ + -H 'Content-Type: application/json' \ + -d '{ + "ticketType": "general", + "ticketDate": "2023-09-07", + "email": "dave@example.com" + }' +``` + +{% admonition type="info" %} +If you call the Redocly mock server and no match is found for the named example passed in the header, the mock server, depending on its configuration, does one of the following: + +- throws an error +- returns another example for that operation +{% /admonition %} + +## Resources + +- [Interact with API documentation](./interact-with-api.md) +- [Test APIs using Replay](./test-apis-replay.md) +- [Use a classic catalog](./use-classic-catalog.md) +- Explore other ways you can interact with the [user interface](./index.md) diff --git a/docs/end-user/test-apis.md b/docs/end-user/test-apis-replay.md similarity index 83% rename from docs/end-user/test-apis.md rename to docs/end-user/test-apis-replay.md index 30fdf358..e48237df 100644 --- a/docs/end-user/test-apis.md +++ b/docs/end-user/test-apis-replay.md @@ -1,9 +1,10 @@ # Test APIs using Replay -You can make API calls directly from the API reference documentation in your project. -Projects that contain API documentation, typically have a tool you can used to try out (test) API requests. +Make API calls directly from the API reference documentation in your project. +Projects that contain API documentation, typically have Replay - the tool you can use to try out (test) API requests. Use Replay to: + - edit any field in sample requests, unrestricted by API description schemas - save requests and view request history - set up and use different environments with customizable variables @@ -19,15 +20,15 @@ Replay is split into two panels, **Request** and **History**. Alternatively, some documentation pages may have an embedded Replay console that is tied to a specific description file. -## Use the Request panel +## Use the Request pane -The Request panel is located on the left side of Replay and includes everything needed to make a request for an endpoint from your API description. +The Request pane is located on the left side of Replay and includes everything needed to make a request for an endpoint from your API description. ### Send a sample request To send a sample request, enter the required parameters and click the **Send** button. -### Response panel +### Response pane After you have sent a sample request, a sample response displays in the bottom of the Request pane. @@ -38,7 +39,7 @@ The sample response is based on example responses included in your API descripti - response headers and values - response cookies -Click the copy icon on the right side of the panel to copy the sample response. +Click the **Copy** icon on the right side of the pane to copy the sample response. ## Work with environments @@ -60,10 +61,10 @@ To switch to a different environment: 1. In Replay's top-right corner, click the **Environments** icon. 1. In the **Environments** window's bottom-left corner, click **New environment**. 1. Enter a name for the environment and confirm. -2. In the **Server** field, hover over **More options** and click **Edit**. -3. Enter the server's URL and click **Save**. -4. (Optional) Expand the **Server variable** field and enter values for server variables. -5. (Optional) In the **Inputs** table you can: +1. In the **Server** field, hover over **More options** and click **Edit**. +1. Enter the server's URL and click **Save**. +1. (Optional) Expand the **Server variable** field and enter values for server variables. +1. (Optional) In the **Inputs** table you can: - Add new inputs and their values. - Edit values of existing inputs. - Set inputs values to secret. @@ -78,10 +79,11 @@ You can edit user-created environments to better suit your needs: - To set values for server variables, expand the **Server variable** field and enter values for server variables. In the **Inputs** table you can: -- Add new inputs and their values. -- Edit values of existing inputs. -- Set inputs values to secret. -- Delete user-added inputs. + +- add new inputs and their values +- edit values of existing inputs +- set input values to secret +- delete user-added inputs ### Set an environment as active @@ -125,11 +127,11 @@ To delete the search history: - In the **History** panel, on the left side of the **Search** field, click the broom icon. -### Collapse the history panel +### Collapse the History panel -You can hide the history panel to make the pages better fit smaller screens. +You can hide the History panel to make the pages better fit smaller screens. -To collapse the history panel: +To collapse the History panel: - In Replay's bottom-left corner, click the **Collapse panel** button. @@ -142,5 +144,6 @@ Otherwise, if you want to see the reference documentation, you can close Replay ## Resources - [Interact with API documentation](./interact-with-api.md) +- [Test APIs using CLI](./test-apis-cli.md) - [Use a classic catalog](./use-classic-catalog.md) - Explore other ways you can interact with the [user interface](./index.md) diff --git a/docs/end-user/use-classic-catalog.md b/docs/end-user/use-classic-catalog.md index 358e22f6..2d4dd410 100644 --- a/docs/end-user/use-classic-catalog.md +++ b/docs/end-user/use-classic-catalog.md @@ -41,5 +41,6 @@ The catalog updates to display APIs with selected tags. - [Interact with API documentation](./interact-with-api.md) - [Interact with pages](./interact-with-pages.md) -- [Test APIs using Replay](./test-apis.md) +- [Test APIs using Replay](./test-apis-replay.md) +- [Test APIs using CLI](./test-apis-cli.md) - Explore other ways you can interact with the [user interface](./index.md) \ No newline at end of file