Skip to content

Instantly share code, notes, and snippets.

@tgj

tgj/threescale-importing-a-swagger-api-configuration.md

Last active October 19, 2021 03:11
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tgj/df6f85e4cc2308c0e548ffd92322d3bc to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tgj/df6f85e4cc2308c0e548ffd92322d3bc to your computer and use it in GitHub Desktop.
Download ZIP
3scale - Importing a Swagger API Configuration
Raw
threescale-importing-a-swagger-api-configuration.md

3scale - Importing a Swagger API Configuration

This tutorial shows how to import a Swagger API Configuration into a 3scale service. A Swagger API configuration of this free-to-use Pet Store Service will be used in this tutorial to import, replicate, and test the endpoints offered by the service, all within the 3scale Management Platform and 3scale CLI.

1. Create a 3scale account

  1. Navigate to the Sign Up page.

  2. Complete the following fields:

    • First Name
    • Last Name
    • Email
    • Password
    • Company / Project name (completing this field generates developer-portal.3scale.net and api-admin-portal.3scale.net fields)

  3. Confirm your account via the confirmation link that was sent to your email address.

  4. Sign In.

  5. Click the X on the notification if one exists after signing in.

2. Install the 3scale CLI

Run the following command inside your Terminal to install the 3scale CLI:

npm install -g node-3scale-cli

3. Configure 3scale CLI

Create an access token

  1. From the dashboard, click the gear icon the top-right of the screen. A menu will appear.

  2. Click Personal Settings.

  3. Click the Tokens tab.

  4. Click Add Access Token.

  5. On the New Access Token page that shows, name the token whatever you want by ensure all Scopes are checked and the Permission is set to Read & Write.

  6. Click Create Access token to create the access token.

  7. IMPORTANT: Copy your access token and additionally store the token in a safe place on your computer (even something as simple as a password protected file would be minimally viable), and keep the current page open as you will need the token for configuring the 3scale CLI.

Configuring the 3scale CLI

  1. Run the following command to configure the 3scale CLI:
    3scale-cli config

  2. For the 3scale access token, enter in the value of the access token you copied/stored on your computer from step 7 of the Create an Access Token path.

  3. For the 3scale id, enter your 3scale username. If you look at the address bar while on the 3scale Management Platform page, your username is contained in the URL of the form of:
    https://yourusername-admin.3scale.net
    Replace yourusername with your 3scale username which appears in the address bar.

  4. For the 3scale wildcard domain, just hit enter (the default should be 3scale.net).

  5. The 3scale-cli should inform you that it has been configured via the following output:
    [3scale-cli] 3scale cli tool configured

4. Import Swagger API Configuration

Feel free to explore the API of this free-to-use Pet Store Service from which we will import its Swagger API configuration.

  1. Acquire the service id of the service automatically created for your account by entering the following command: 3scale-cli services list. A table will appear with one of the column headers being id. Copy the numerical id under the column header of your service for the next step.

  2. To import all of the methods of the API Configuration of the Pet Store Service, enter the following command: 3scale-cli import swagger -f http://petstore.swagger.io/v2/swagger.json -m "true" -s SERVICE_ID
    where SERVICE_ID is the id you copied in the previous step.

Explanation of command options:

  • 3scale-cli import swagger instructs the 3scale CLI to import a Swagger API configuration.
  • -f [URI-TO-API-CONFIG] specifies the URI to the configuration file.
  • -m "true" instructs to import all the API endpoints of the configuration.
  • -s SERVICE_ID specifies the id of the 3scale service.
  1. The import processing time is a function of the amount of endpoints specified in the API configuration file. Once the import completes, the 3scale-cli should inform you, like so:
    [3scale-cli] Import on 3scale complete

5. Verify a Swagger API configuration is imported to a 3scale service

  1. Click the API tab within the management platform.

  2. On the left hand side of the screen, there should be a title named API and three links under the title: Defintion, Integration, and Services. Click Definition.

  3. From the Definition page, you can see the Methods and Metrics your API definition comprises of. Each method has a Friendly name and a System name - one allows you to reference what a method does easily, the other is used as a reference within the 3scale service.

  4. If you want to modify or delete the mapping of a method, click the ✓ under the Mapped column within the Methods listing table. This will take you to the service’s Integration page, which additionally allows you to modify the API and API Gateway settings of your service.

  5. To truly verify that our Swagger API configuration was successfully imported into our service, change the Private Base URL to http://petstore.swagger.io:80 to route requests to our service to the Pet Store service. Scroll to the bottom of the page and click Update & test in Staging Environment.

  6. At the bottom of the same page, in the API test GET request field, enter /v2/pet/1. Copy the curl command and paste the result in your terminal. Verify the result is similar to the one below:
    {"id":1,"category":{"id":0,"name":"string"},"name":"1","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"1"}

  7. Congrats! You’ve successfully imported a Swagger API configuration into your own 3scale service and verified its behavior by using an existing service to make your very own!

Bonus! Create Documentation from a Swagger API configuration

  1. Back in the 3scale management platform within the web browser, click the API tab.

  2. Right below the 3scale logo on the left side of the page, there should be two links: Overview and ActiveDocs. Click ActiveDocs.

  3. This takes you to the ActiveDocs page, which lists the specifications of Swagger APIs. We are going to create a new specification by importing the specification of the Pet Store Service. Click Create a new spec to create a new specification.

  4. For Name enter Pet Store

  5. For System name enter pet-store.

  6. For the API JSON Spec we’re going to need the contents of the Swagger API configuration we imported earlier into our service. To copy the contents of this file into your clipboard, run the following command in the terminal:
    curl http://petstore.swagger.io/v2/swagger.json | pbcopy
    Copy the results into the API JSON Spec field. Click Create Service to generate the documentation for the API. Notice the level of detail and organization of the documentation, which additionally lets you test each endpoint of the Pet Store service.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment