azure/apicenter-analyzer

Analyze your API Specs with Azure API Center (Preview)

Analyze your API Specs with Azure API Center (Preview)

Overview

• 💡 What is Azure API Center?
  • 📝 API Governance & Azure API Center
  • 📝 API Analysis in Azure API Center (Overview)
• 🚀 How to Run
  • 🔧 Configure your environment
  • 🔧 Running the sample using the Azure Developer CLI (azd)
  • 🔧 Configure & run your function locally
• 📦 How to deploy
• 📄 Custom Ruleset
• ✏️ Contributing
• ☀️ Bugs & Issues & Feedback
• 🚧 Code of Conduct
• 👌 Trademark Notice
• 🔍 Telemetry

💡 What is Azure API Center?

Azure API Center is a service that helps you develop and maintain a structured inventory of your organization’s APIs. With API Center, you can track all of your APIs in a centralized location, regardless of their type, lifecycle stage, or deployment location. API Center enables API discovery, reuse, and governance empowering API Platform Teams.

📝 API Governance & Azure API Center

API governance is a critical aspect of managing APIs across an organization. It involves establishing and enforcing policies and procedures that guarantee the quality, consistency, security, and compliance of APIs. Effective API governance not only maximizes the value of an organization's API portfolio but also reduces complexity, eliminates redundancy, and mitigates potential risks.

For API Platform Teams, governance is crucial as it guides them in designing, building, and deploying APIs that align with the organization's objectives, standards, and best practices.

To facilitate robust API governance, we're excited to introduce API Analysis in Azure API Center. API Analysis employs API linting, a technique that validates your API specifications against a predefined set of rules or standards. With API Analysis, you can ensure your APIs adhere to your organization's guidelines and best practices, making them consistently secure and compliant.

API Analysis currently supports OpenAPI v2, v3.x, and AsyncAPI specifications uploaded as JSON or YAML files.

📝 API Analysis in Azure API Center (Overview)

Here is a high-level overview of how API analysis works in Azure API Center

🚀 How to Run API Analysis

🔧 Configure your environment

Before you get started, make sure you have the following requirements in place:

• An Azure account with an active subscription. Create an account for free.
• Node.js 18.x or above. Use the node --version command to check your version.
• TypeScript 4.x. Use the tsc -v command to check your version.
• Visual Studio Code on one of the supported platforms.
• The Azure Functions extension v1.10.4 or above for Visual Studio Code.
• Azure Functions Core Tools v4.0.5382 or above.
• Azure Developer CLI.
• Azure CLI.

🔧 Running the sample using the Azure Developer CLI (azd)

The Azure Developer CLI (azd) is a developer-centric command-line interface (CLI) tool for creating Azure applications.

After logging in with the following command, you will be able to use the azd cli to quickly provision and deploy the application.

# Authenticate with Azure Developer CLI
azd auth login

# Authenticate with Azure CLI
az login

Then, run azd up to provision all the resources to Azure and deploy the code to those resources.

azd up

Enter an environment name and select your desired subscription and location. Then choose whether to create the monitoring resources. If you want to use an existing api center resource, pass the values for apiCenterName and apiCenterResourceGroupName. Otherwise leave them blank to create a new one. Wait a moment for the resource deployment to complete. Then you can upload your own api definition for test.

There are four scenarios:

1. New APIC with monitoring. You need to leave apiCenterName and apiCenterResourceGroupName blank and set useMonitoring to "True".
2. New APIC without monitoring. You need to leave apiCenterName and apiCenterResourceGroupName blank and set useMonitoring to "False".
3. Existing APIC with monitoring. You need to fill in apiCenterName and apiCenterResourceGroupName with an existing resource and set useMonitoring to "True".
4. Existing APIC without monitoring. You need to fill in apiCenterName and apiCenterResourceGroupName with an existing resource and set useMonitoring to "False".

(Optional) You can also set the Env variables manually using the following command to skip setting them during the azd up process.

azd env set USE_MONITORING <true/false>

azd env set APIC_NAME <your-api-center-name>

azd env set APIC_RESOURCE_GROUP_NAME <your-api-center-resource-group-name>

You can also run the sample directly locally (See below).

🔧 Configure & run your function locally

• Clone the APICenter-Analyzer repository to your local machine.
• Open the Project in Visual Studio Code
• Set a breakpoint
• To start the function locally, press F5 or the Run and Debug icon in the left-hand side Activity bar. The Terminal panel should display the Output from Azure Functions Core Tools.
• Follow the instructions in Test your Event Grid handler locally to trigger the function.

📦 How to deploy

Follow the instructions in Quickstart: Create a function in Azure with TypeScript using Visual Studio Code. Start from the "Sign in to Azure" section and complete all subsequent sections.

📄 Custom Ruleset

This template provides you with the default OAS (OpenAPI Specification) ruleset from Spectral. To see the exact rules within the ruleset, see OpenAPI Rules.

If you want to customize your Ruleset for analysis, simply swap out the default ruleset file oas.yaml located in {workSpaceFolder}/resources/rulesets with any valid Spectral ruleset file. We accept all valid Spectral formats (YAML, JSON, and JavaScript). Afterward, head over to the {workSpaceFolder}/src/constants.ts file and update the RulesetFileName constant with your chosen ruleset file name.

✏️ Contributing

See the contribution guidelines for ideas and guidance on how to improve the template. Thank you!

☀️ Bugs & Issues & Feedback

We Love Hearing From You!

Your feedback is invaluable to us, and we encourage you to share your thoughts and suggestions in the repository's Issues section. You can also report bugs or submit feature requests there. Rest assured, we’ll be keeping a close eye on your input to continuously improve. While we’re dedicated to monitoring these issues, please note that this channel is not part of our Microsoft Azure Service Support.

Microsoft Azure Support assistance is limited to the initial setup of the Azure Function app that runs the linting engine. Best effort support is provided for problems that are caused by environmental factors, such as (but not limited to): hosting platform, development environment, network configuration.

If you need technical assistance with extending the linting engine or improving existing rules , please leverage existing technical communities such as Stack Overflow. We don't provide support through GitHub Issues.

We welcome and appreciate community contributions.

🚧 Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

👌 Trademark Notice

Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

🔍 Telemetry

Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

License

MIT

apicenter-analyzer's Issues

Register azd template in `awesome-azd` repo

Bug: API Definition is Analyzer is not in pretty format,

if the API is import via the az apic register cli the format in the Analyzer is not in pretty format making it impossible to view errors , if upload the same definition via the portal its fine.

Action required: migrate or opt-out of migration to GitHub inside Microsoft

Migrate non-Open Source or non-External Collaboration repositories to GitHub inside Microsoft

In order to protect and secure Microsoft, private or internal repositories in GitHub for Open Source which are not related to open source projects or require collaboration with 3rd parties (customer, partners, etc.) must be migrated to GitHub inside Microsoft a.k.a GitHub Enterprise Cloud with Enterprise Managed User (GHEC EMU).

Action

✍️ Please RSVP to opt-in or opt-out of the migration to GitHub inside Microsoft.

❗Only users with admin permission in the repository are allowed to respond. Failure to provide a response will result to your repository getting automatically archived.🔒

Instructions

Reply with a comment on this issue containing one of the following optin or optout command options below.

✅ Opt-in to migrate

@gimsvc optin --date <target_migration_date in mm-dd-yyyy format>

Example: @gimsvc optin --date 03-15-2023

OR

❌ Opt-out of migration

@gimsvc optout --reason <staging|collaboration|delete|other>

Example: @gimsvc optout --reason staging

Options:

• staging : This repository will ship as Open Source or go public
• collaboration : Used for external or 3rd party collaboration with customers, partners, suppliers, etc.
• delete : This repository will be deleted because it is no longer needed.
• other : Other reasons not specified

Need more help? 🖐️

• Email [email protected]. ✉️
• Post your questions in GitHub inside Microsoft Team in Microsoft Teams. 🗨️

Using functions in the ruleset

Do you have an example of using function in the workset

I tried with the following ruleset and function but it fails to run

# Source: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules
extends:
 - spectral:oas
functionsDir: "./functions"
functions:
 - consistent-response-body
rules:
 info-contact: off
 no-$ref-siblings: off
 oas2-api-host: off
 oas2-api-schemes: off
 openapi-tags: off
 operation-description: off
 operation-tags: off
 operation-tag-defined: off

 # Note: The Spectral VSCode extension will not display "hint" messages, so
 # use "info" rather than "hint".
 # just a note here

 az-additional-properties-and-properties:
   description: Don't specify additionalProperties as a sibling of properties.
   severity: warn
   formats: ["oas2", "oas3"]
   given: $..[?(@object() && @.type === 'object' && @.properties)]
   then:
     field: additionalProperties
     function: falsy


 az-consistent-response-body:
   description: Ensure the get, put, and patch response body schemas are consistent.
   message: "{{error}}"
   severity: warn
   formats: ["oas2"]
   given: $.paths.*
   then:
     function: consistent-response-body

and function

// If put or patch is a create (returns 201), then verify that put, get, and patch response body
// schemas are consistent.

// path Item should be a [path item object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#pathItemObject).
// This function assumes it is running on a resolved doc.
module.exports = (pathItem, _opts, paths) => {
if (pathItem === null || typeof pathItem !== 'object') {
  return [];
}
const path = paths.path || paths.target || [];

const errors = [];

// resource schema is create operation response schema
const createResponseSchema = ((op) => op?.responses?.['201']?.schema);
const resourceSchema = createResponseSchema(pathItem.put) || createResponseSchema(pathItem.patch);
if (resourceSchema) {
  ['put', 'get', 'patch'].forEach((method) => {
    const responseSchema = pathItem[method]?.responses?.['200']?.schema;
    if (responseSchema && responseSchema !== resourceSchema) {
      errors.push({
        message: 'Response body schema does not match create response body schema.',
        path: [...path, method, 'responses', '200', 'schema'],
      });
    }
  });
}

return errors;
};

This is based upon the azure ruleset azure-api-style-guide

Ive also attached the azure fucntions logs
query_data.csv
log