Lab 4 - API Documentation
In this lab, you will generate and test an ActiveDocs documentation for the API created in the 2nd lab.
- Open a web browser and go to https://3scale-admin.3scale.suffix_value
- Login as admin/admin
- Click on the APIs tab.
- Click on the AciveDocs link.
- Click on the Create a new spec.
- Enter the following values:
| Parameter | Value |
|---|---|
| Name | Products |
| System Name | products_spec |
| Publish? | checked |
| Description | Products API Documentation |
- Open a new web browser tab, and go to http://apicurio-studio.suffix_value
If you get a certificate error, click on the Proceed to.. link.
- Click on the Register link.
- Complete the form with the following values:
| Parameter | Value |
|---|---|
| First Name | Username |
| Last Name | Lastname |
| [email protected] | |
| Password | password |
| Confirm Password | password |
- Click on the Register button.
- Click on the Import API button.
- Enter the following URL: http://products.suffix_value/rest/swagger.yaml
This API was built using Swagger/OpenAPI annotations, so it will automatically and dynamically generate an OpenAPI document that describes its operations, parameters, etc. that you can get by accessing that URL (/rest/swagger.yaml).
- Click on the Import API button.
- Click on the Edit API button.
You will add a "security scheme" to the API to secure it using API Keys.
- Click on the Add a security scheme link.
- Enter the following values:
| Parameter | Value |
|---|---|
| Name | apiKey |
| Security | API Key |
| Key Location | Query Parameter |
| Name | user_key |
Click on the OK button.
Click on the Add security requirement link.
- Check the apiKey security requirement.
- Click on the OK button.
- Click on the APIs >> Products breadcrumb link.
- Click on the three dots in the Products API and select Download (JSON).
- Save the Products.json file in your computer.
- Close Apicurio, and go back to the 3Scale admin console web browser tab.
- Open the downloaded Products.json file with any text editor, and copy its contents.
- Paste it into the API JSON Spec field.
- Replace host field value with: products-apicast-staging.3scale.suffix_value:443
- Change the http scheme to https.
We want the OpenAPI document to point to the API Gateway URL instead of the API directly.
- Scroll down to the bottom of the page, and click on the Create Service button.
- Click on the Applicatios tab.
- Click on the ProductsApp application.
- Copy the User Key under API Credentials
- Click on the APIs tab.
- Click on the ActiveDocs tab.
- Click on the Products spec.
- Expand the GET /services/allproducts operation.
- Click on the red circle with an exclamation sign.
- Paste the User Key into the value field.
- Click on the Authorize button.
- Click on the Try it Out! button.
- You should get a successful response like the following:
- If you get a “No Content” error:
- Copy the Request URL, open a new tab and paste the URL.
- Accept the certificate.
- Close the tab and test the API again.