api-center-analyzer-integration-nodejs.md

API Center Analyzer Integration

You can analyze your API documents using Visual Studio Code (Standalone) or Azure Portal (Server-Side). This section will guide you through the integration process.

Standalone Analyzer through Visual Studio Code

To use this standalone analyzer, you need to install the API Center extension in Visual Studio Code.

1. Install dependencies.

   cd nodejs/webapi && npm install

2. Install dependencies.

   cd nodejs/webapi && npm install

3. Run the sample app.

   npm start

   Navigate to http://localhost:3030/api-docs/swagger to view the Swagger UI page.

   

4. Navigate to http://localhost:3030/api-docs/swagger.json to see the OpenAPI document.

   

5. Save the OpenAPI document to weatherforecast.json.

6. Stop the sample app by pressing Ctrl+C.

7. Open weatherforecast.json in Visual Studio Code. You'll see many yellow lines and red lines

   

8. Type F1 then select "Azure API Center: Set active API Style Guide".

   

   You will have several options to choose the styles. Choose either Microsoft Azure REST API or OWASP API Security Top 10 and see the analysis results.

   

9. You can also choose the custom API style guide that reflects your organization's policies. This time choose Select Local File then select the resources/rulesets/oas.yaml file. You'll still see many yellow lines and red lines. Hover your mouse and see what needs to be fixed.

   

10. Open nodejs/webapi/app.js,

    • Find the following code block:

      // route to serve basic/ improved JSON
      app.get("/api-docs/swagger.json", (req, res) => {
      // res.send(swaggerSpecs.improved);
      res.send(swaggerSpecs.basic);
      });

    • Uncomment the line res.send(swaggerSpecs.improved);

    • Comment out the line res.send(swaggerSpecs.basic);

      // route to serve basic/ improved JSON
      app.get("/api-docs/swagger.json", (req, res) => {
      res.send(swaggerSpecs.improved);
      // res.send(swaggerSpecs.basic);
      });

11. Then find the following code block:

    // setupSwaggerUi(app, swaggerSpecs.improved, "/api-docs/swagger");
    setupSwaggerUi(app, swaggerSpecs.basic, '/api-docs/swagger');

    • Uncomment the line // setupSwaggerUi(app, swaggerSpecs.improved, "/api-docs/swagger");

    • Comment out the line setupSwaggerUi(app, swaggerSpecs.basic, '/api-docs/swagger');

      setupSwaggerUi(app, swaggerSpecs.improved, "/api-docs/swagger");
      // setupSwaggerUi(app, swaggerSpecs.basic, '/api-docs/swagger');

12. Run the sample app again. Ensure you are still in nodejs/webapi

    npm start

    You'll see the following Swagger UI page.

    

13. Navigate to http://localhost:3030/api-docs/swagger.json to see the OpenAPI document.

    

14. Save the OpenAPI document to weatherforecast-reviewed.json.

15. Stop the sample app by pressing Ctrl+C.

16. Open weatherforecast-reviewed.json in Visual Studio Code. You'll see all yellow lines and red lines disappeared.

    

Server-Side Analyzer through Azure Portal

To use this server-side analysis feature, you need to install the APICenter Analyzer first.

Install APICenter Analyzer

APICenter Analyzer is a tool to analyze API specifications on the server-side. If you want to integrate this server-side analysis feature, you can install it by following steps.

1. In a separate directory, say ~/apic-analyzer, clone the APICenter Analyzer repository.

   azd init --template Azure/APICenter-Analyzer --branch preview

   You will be asked to provide the environment name. Give it a different name from the one holding the existing API Center.

2. Copy over the ruleset to the APICenter Analyzer repository.

   # Bash
   cp resources/rulesets/oas.yaml ~/apic-analyzer/resources/rulesets/
   
   # PowerShell
   Copy-Item -Path resources/rulesets/oas.yaml -Destination ~/apic-analyzer/resources/rulesets/

3. Provision resources to Azure and deploy the app.

   azd up

   You will have to provide the existing API Center instance name and its resource group name for integration.

Server-Side Analysis by Registering API

1. Register weatherforecast.json to API Center through Azure Portal or through this document, API Registration.

2. Check the warnings in the API Center.

3. Check the warnings in the API Center.

   

4. Update existing API definition with weatherforecast-reviewed.json to API Center through Azure Portal or through this document, API Registration.

5. Check the warnings in the API Center.

6. Check the warnings in the API Center.