Last active
October 19, 2021 03:11
-
-
Save tgj/df6f85e4cc2308c0e548ffd92322d3bc to your computer and use it in GitHub Desktop.
Revisions
-
tgj revised this gist
Apr 16, 2018 . 1 changed file with 1 addition and 1 deletion.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -22,7 +22,7 @@ <p>Sign In.</p> </li> <li> <p>Click the <code>X</code> on the notification if one exists after signing in.</p> </li> </ol> <h2 id="install-the-3scale-cli">2. Install the 3scale CLI</h2> -
Mar 26, 2018 . 1 changed file with 1 addition and 1 deletion.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -80,7 +80,7 @@ Replace <em>yourusername</em> with your 3scale username which appears in the add <p>Feel free to explore the API of <a href="http://petstore.swagger.io/">this free-to-use Pet Store Service</a> from which we will import its Swagger API configuration.</p> <ol> <li> <p>Acquire the service id of the service automatically created for your account by entering the following command: <code>3scale-cli services list</code>. A table will appear with one of the column headers being <em>id</em>. Copy the numerical id under the column header of your service for the next step.</p> </li> <li> <p>To import all of the methods of the API Configuration of the Pet Store Service, enter the following command: <code>3scale-cli import swagger -f http://petstore.swagger.io/v2/swagger.json -m "true" -s SERVICE_ID</code><br> -
Mar 24, 2018 . 1 changed file with 0 additions and 0 deletions.There are no files selected for viewing
File renamed without changes. -
Mar 23, 2018 . No changes.There are no files selected for viewing
-
Mar 23, 2018 . 1 changed file with 0 additions and 151 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -1,151 +0,0 @@ -
Mar 23, 2018 . No changes.There are no files selected for viewing
-
Mar 23, 2018 . 1 changed file with 151 additions and 0 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,151 @@ <h1 id="scale---importing-a-swagger-api-configuration">3scale - Importing a Swagger API Configuration</h1> <p>This tutorial shows how to import a Swagger API Configuration into a 3scale service. A Swagger API configuration of <a href="http://petstore.swagger.io/">this free-to-use Pet Store Service</a> 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.</p> <h2 id="create-a-3scale-account">1. Create a 3scale account</h2> <ol> <li> <p>Navigate to the Sign Up <a href="https://www.3scale.net/signup/">page</a>.</p> </li> <li> <p>Complete the following fields:</p> <ul> <li><code>First Name</code></li> <li><code>Last Name</code></li> <li><code>Email</code></li> <li><code>Password</code></li> <li><code>Company / Project name</code> (completing this field generates <code>developer-portal.3scale.net</code> and <code>api-admin-portal.3scale.net</code> fields)</li> </ul> </li> <li> <p>Confirm your account via the confirmation link that was sent to your email address.</p> </li> <li> <p>Sign In.</p> </li> <li> <p>Click the <code>X</code> on the notification f one exists after signing in.</p> </li> </ol> <h2 id="install-the-3scale-cli">2. Install the 3scale CLI</h2> <p>Run the following command inside your Terminal to install the 3scale CLI:</p> <pre><code>npm install -g node-3scale-cli </code></pre> <h2 id="configure-3scale-cli">3. Configure 3scale CLI</h2> <h3 id="create-an-access-token">Create an access token</h3> <ol> <li> <p>From the dashboard, click the gear icon the top-right of the screen. A menu will appear.</p> </li> <li> <p>Click <strong>Personal Settings</strong>.</p> </li> <li> <p>Click the <strong>Tokens</strong> tab.</p> </li> <li> <p>Click <strong>Add Access Token</strong>.</p> </li> <li> <p>On the <strong>New Access Token</strong> page that shows, name the token whatever you want by ensure all <strong>Scopes</strong> are checked and the <strong>Permission</strong> is set to <strong>Read & Write</strong>.</p> </li> <li> <p>Click <strong>Create Access token</strong> to create the access token.</p> </li> <li> <p><strong>IMPORTANT:</strong> 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.</p> </li> </ol> <h3 id="configuring-the-3scale-cli">Configuring the 3scale CLI</h3> <ol> <li> <p>Run the following command to configure the 3scale CLI:<br> <code>3scale-cli config</code></p> </li> <li> <p>For the <strong>3scale access token</strong>, enter in the value of the access token you copied/stored on your computer from step 7 of the <a href="#create-an-access-token">Create an Access Token</a> path.</p> </li> <li> <p>For the <strong>3scale id</strong>, 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:<br> <code>https://yourusername-admin.3scale.net</code><br> Replace <em>yourusername</em> with your 3scale username which appears in the address bar.</p> </li> <li> <p>For the <strong>3scale wildcard domain</strong>, just hit enter (the default should be <code>3scale.net</code>).</p> </li> <li> <p>The 3scale-cli should inform you that it has been configured via the following output:<br> <code>[3scale-cli] 3scale cli tool configured</code></p> </li> </ol> <h2 id="import-swagger-api-configuration">4. Import Swagger API Configuration</h2> <p>Feel free to explore the API of <a href="http://petstore.swagger.io/">this free-to-use Pet Store Service</a> from which we will import its Swagger API configuration.</p> <ol> <li> <p>Acquire the service id of the service automatically created for your account by entering the following command: <code>3scale services list</code>. A table will appear with one of the column headers being <em>id</em>. Copy the numerical id under the column header of your service for the next step.</p> </li> <li> <p>To import all of the methods of the API Configuration of the Pet Store Service, enter the following command: <code>3scale-cli import swagger -f http://petstore.swagger.io/v2/swagger.json -m "true" -s SERVICE_ID</code><br> where <code>SERVICE_ID</code> is the id you copied in the previous step.</p> </li> </ol> <blockquote> <p>Explanation of command options:</p> <ul> <li><code>3scale-cli import swagger</code> instructs the 3scale CLI to import a Swagger API configuration.</li> <li><code>-f [URI-TO-API-CONFIG]</code> specifies the URI to the configuration file.</li> <li><code>-m "true"</code> instructs to import all the API endpoints of the configuration.</li> <li><code>-s SERVICE_ID</code> specifies the id of the 3scale service.</li> </ul> </blockquote> <ol start="3"> <li>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:<br> <code>[3scale-cli] Import on 3scale complete</code></li> </ol> <h2 id="verify-a-swagger-api-configuration-is-imported-to-a-3scale-service">5. Verify a Swagger API configuration is imported to a 3scale service</h2> <ol> <li> <p>Click the <strong>API</strong> tab within the management platform.</p> </li> <li> <p>On the left hand side of the screen, there should be a title named <strong>API</strong> and three links under the title: <em>Defintion</em>, <em>Integration</em>, and <em>Services</em>. Click <strong>Definition</strong>.</p> </li> <li> <p>From the Definition page, you can see the Methods and Metrics your API definition comprises of. Each method has a <em>Friendly name</em> and a <em>System name</em> - one allows you to reference what a method does easily, the other is used as a reference within the 3scale service.</p> </li> <li> <p>If you want to modify or delete the mapping of a method, click the ✓ under the <em>Mapped</em> column within the Methods listing table. This will take you to the service’s <em>Integration</em> page, which additionally allows you to modify the API and API Gateway settings of your service.</p> </li> <li> <p>To truly verify that our Swagger API configuration was successfully imported into our service, change the <strong>Private Base URL</strong> to <code>http://petstore.swagger.io:80</code> to route requests to our service to the Pet Store service. Scroll to the bottom of the page and click <strong>Update & test in Staging Environment</strong>.</p> </li> <li> <p>At the bottom of the same page, in the <strong>API test GET request</strong> field, enter <code>/v2/pet/1</code>. Copy the <code>curl</code> command and paste the result in your terminal. Verify the result is similar to the one below:<br> <code>{"id":1,"category":{"id":0,"name":"string"},"name":"1","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"1"}</code></p> </li> <li> <p>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!</p> </li> </ol> <h2 id="bonus-create-documentation-from-a-swagger-api-configuration">Bonus! Create Documentation from a Swagger API configuration</h2> <ol> <li> <p>Back in the 3scale management platform within the web browser, click the <strong>API</strong> tab.</p> </li> <li> <p>Right below the 3scale logo on the left side of the page, there should be two links: <em>Overview</em> and <em>ActiveDocs</em>. Click <strong>ActiveDocs</strong>.</p> </li> <li> <p>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 <a href="http://petstore.swagger.io/">Pet Store Service</a>. Click <strong>Create a new spec</strong> to create a new specification.</p> </li> <li> <p>For <strong>Name</strong> enter <strong>Pet Store</strong></p> </li> <li> <p>For <strong>System name</strong> enter <strong>pet-store</strong>.</p> </li> <li> <p>For the <strong>API JSON Spec</strong> 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:<br> <code>curl http://petstore.swagger.io/v2/swagger.json | pbcopy</code><br> Copy the results into the <strong>API JSON Spec</strong> field. Click <strong>Create Service</strong> 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.</p> </li> </ol> -
Mar 23, 2018 . No changes.There are no files selected for viewing
-
Mar 23, 2018 . 1 changed file with 0 additions and 0 deletions.There are no files selected for viewing
File renamed without changes. -
Mar 23, 2018 .There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,151 @@ <h1 id="scale---importing-a-swagger-api-configuration">3scale - Importing a Swagger API Configuration</h1> <p>This tutorial shows how to import a Swagger API Configuration into a 3scale service. A Swagger API configuration of <a href="http://petstore.swagger.io/">this free-to-use Pet Store Service</a> 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.</p> <h2 id="create-a-3scale-account">1. Create a 3scale account</h2> <ol> <li> <p>Navigate to the Sign Up <a href="https://www.3scale.net/signup/">page</a>.</p> </li> <li> <p>Complete the following fields:</p> <ul> <li><code>First Name</code></li> <li><code>Last Name</code></li> <li><code>Email</code></li> <li><code>Password</code></li> <li><code>Company / Project name</code> (completing this field generates <code>developer-portal.3scale.net</code> and <code>api-admin-portal.3scale.net</code> fields)</li> </ul> </li> <li> <p>Confirm your account via the confirmation link that was sent to your email address.</p> </li> <li> <p>Sign In.</p> </li> <li> <p>Click the <code>X</code> on the notification f one exists after signing in.</p> </li> </ol> <h2 id="install-the-3scale-cli">2. Install the 3scale CLI</h2> <p>Run the following command inside your Terminal to install the 3scale CLI:</p> <pre><code>npm install -g node-3scale-cli </code></pre> <h2 id="configure-3scale-cli">3. Configure 3scale CLI</h2> <h3 id="create-an-access-token">Create an access token</h3> <ol> <li> <p>From the dashboard, click the gear icon the top-right of the screen. A menu will appear.</p> </li> <li> <p>Click <strong>Personal Settings</strong>.</p> </li> <li> <p>Click the <strong>Tokens</strong> tab.</p> </li> <li> <p>Click <strong>Add Access Token</strong>.</p> </li> <li> <p>On the <strong>New Access Token</strong> page that shows, name the token whatever you want by ensure all <strong>Scopes</strong> are checked and the <strong>Permission</strong> is set to <strong>Read & Write</strong>.</p> </li> <li> <p>Click <strong>Create Access token</strong> to create the access token.</p> </li> <li> <p><strong>IMPORTANT:</strong> 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.</p> </li> </ol> <h3 id="configuring-the-3scale-cli">Configuring the 3scale CLI</h3> <ol> <li> <p>Run the following command to configure the 3scale CLI:<br> <code>3scale-cli config</code></p> </li> <li> <p>For the <strong>3scale access token</strong>, enter in the value of the access token you copied/stored on your computer from step 7 of the <a href="#create-an-access-token">Create an Access Token</a> path.</p> </li> <li> <p>For the <strong>3scale id</strong>, 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:<br> <code>https://yourusername-admin.3scale.net</code><br> Replace <em>yourusername</em> with your 3scale username which appears in the address bar.</p> </li> <li> <p>For the <strong>3scale wildcard domain</strong>, just hit enter (the default should be <code>3scale.net</code>).</p> </li> <li> <p>The 3scale-cli should inform you that it has been configured via the following output:<br> <code>[3scale-cli] 3scale cli tool configured</code></p> </li> </ol> <h2 id="import-swagger-api-configuration">Import Swagger API Configuration</h2> <p>Feel free to explore the API of <a href="http://petstore.swagger.io/">this free-to-use Pet Store Service</a> from which we will import its Swagger API configuration.</p> <ol> <li> <p>Acquire the service id of the service automatically created for your account by entering the following command: <code>3scale services list</code>. A table will appear with one of the column headers being <em>id</em>. Copy the numerical id under the column header of your service for the next step.</p> </li> <li> <p>To import all of the methods of the API Configuration of the Pet Store Service, enter the following command: <code>3scale-cli import swagger -f http://petstore.swagger.io/v2/swagger.json -m "true" -s SERVICE_ID</code><br> where <code>SERVICE_ID</code> is the id you copied in the previous step.</p> </li> </ol> <blockquote> <p>Explanation of command options:</p> <ul> <li><code>3scale-cli import swagger</code> instructs the 3scale CLI to import a Swagger API configuration.</li> <li><code>-f [URI-TO-API-CONFIG]</code> specifies the URI to the configuration file.</li> <li><code>-m "true"</code> instructs to import all the API endpoints of the configuration.</li> <li><code>-s SERVICE_ID</code> specifies the id of the 3scale service.</li> </ul> </blockquote> <ol start="3"> <li>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:<br> <code>[3scale-cli] Import on 3scale complete</code></li> </ol> <h2 id="verify-a-swagger-api-configuration-is-imported-to-a-3scale-service">Verify a Swagger API configuration is imported to a 3scale service</h2> <ol> <li> <p>Click the <strong>API</strong> tab within the management platform.</p> </li> <li> <p>On the left hand side of the screen, there should be a title named <strong>API</strong> and three links under the title: <em>Defintion</em>, <em>Integration</em>, and <em>Services</em>. Click <strong>Definition</strong>.</p> </li> <li> <p>From the Definition page, you can see the Methods and Metrics your API definition comprises of. Each method has a <em>Friendly name</em> and a <em>System name</em> - one allows you to reference what a method does easily, the other is used as a reference within the 3scale service.</p> </li> <li> <p>If you want to modify or delete the mapping of a method, click the ✓ under the <em>Mapped</em> column within the Methods listing table. This will take you to the service’s <em>Integration</em> page, which additionally allows you to modify the API and API Gateway settings of your service.</p> </li> <li> <p>To truly verify that our Swagger API configuration was successfully imported into our service, change the <strong>Private Base URL</strong> to <code>http://petstore.swagger.io:80</code> to route requests to our service to the Pet Store service. Scroll to the bottom of the page and click <strong>Update & test in Staging Environment</strong>.</p> </li> <li> <p>At the bottom of the same page, in the <strong>API test GET request</strong> field, enter <code>/v2/pet/1</code>. Copy the <code>curl</code> command and paste the result in your terminal. Verify the result is similar to the one below:<br> <code>{"id":1,"category":{"id":0,"name":"string"},"name":"1","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"1"}</code></p> </li> <li> <p>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!</p> </li> </ol> <h2 id="bonus-create-documentation-from-a-swagger-api-configuration">Bonus: Create Documentation from a Swagger API configuration</h2> <ol> <li> <p>Back in the 3scale management platform within the web browser, click the <strong>API</strong> tab.</p> </li> <li> <p>Right below the 3scale logo on the left side of the page, there should be two links: <em>Overview</em> and <em>ActiveDocs</em>. Click <strong>ActiveDocs</strong>.</p> </li> <li> <p>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 <a href="http://petstore.swagger.io/">Pet Store Service</a>. Click <strong>Create a new spec</strong> to create a new specification.</p> </li> <li> <p>For <strong>Name</strong> enter <strong>Pet Store</strong></p> </li> <li> <p>For <strong>System name</strong> enter <strong>pet-store</strong>.</p> </li> <li> <p>For the <strong>API JSON Spec</strong> 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:<br> <code>curl http://petstore.swagger.io/v2/swagger.json | pbcopy</code><br> Copy the results into the <strong>API JSON Spec</strong> field. Click <strong>Create Service</strong> 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.</p> </li> </ol>