API Management schema import tools

This repository contains the source code for several tools that are useful to prepare and upload WSDL and XML schema files for use in your Azure API Management service instance:

• WSDLProcessor: Takes a WSDL file as an input and outputs another WSDL file with references through wsdl:import, xsd:import, and xsd:include resolved and merged inline. The references are resolved from the local filesystem or through a URL.
• XMLSchemaProcessor: Takes a folder with XSD files, renames them based on Azure Resource Manager naming requirements, and creates a sequence to upload those schemas into Azure API Management based on a schema dependency graph
• PowerShell tools
  • uploadschemas.ps1: Uploads the XSD schema files generated by the XMLSchemaProcessor to your Azure API Management service
  • batchWsdlProcessor.ps1: Runs WSDLProcessor on all WSDL files with location specified in a JSON file and uploads the generated WSDL files into your Azure API Management service
  • batchXmlSchemaProcessor.ps1: Runs XMLSchemaProcessor for all folders listed in a JSON file and uploads the generated XSD schemas into your Azure API Management service

Features

WSDLProcessor

This project framework provides the following features:

• Accepts two command-line parameters:
  • Path to input WSDL file
  • Path to output WSDL file
• Detects, resolves, and inlines:
  • All wsdl:import directives
  • All xsd:import and xsd:include elements in XML schemas
• Merges all XML schemas with the same target namespace into a single schema
• Resolves the following types of references:
  • HTTP/HTTPS absolute URLs. Any non-200 response is a failure.
  • Absolute local filesystem locations
  • Relative local filesystem locations. For the base location, the tool uses the current file location, not root file location or the location of the tool itself.
• Outputs a single WSDL file

XMLSchemaProcessor

This tool provides the following features:

• Accepts two command-line parameters:
  • A folder with all schemas
  • Output folder
• Produces a single file upload-plan.json in the output folder
• Performs the following steps:

  • Iterates through all files in the folder with .xsd extension

  • Detects all xsd:import and xsd:include elements

  • Fails immediately if any import or include doesn't have schemaLocation or the value is not a local file location

  • For each filename, generates an Azure Resource Manager-compliant resource name:

    • Drops file extension

    • Replaces all non-alphanumeric symbols with a single dash

      Examples: foo.xsd -> foo, foo_1.xsd -> foo-1, foo_1_2.xsd -> foo-1-2, etc.

  • Replaces schemaLocation with a reference to a well-formed ARM schema resource: foo.xsd -> /schemas/foo, foo_1_2.xsd -> /schemas/foo-1-2

  • Builds a dependency graph between all schema files

  • Writes a single JSON document in the output file with property names corresponding to filenames and property values corresponding to ARM names in the order of dependency

    Example: If foo.xsd depends on foo_1_2.xsd, upload-plan.json should contain: { "foo_1_2.xsd": "foo-1-2", "foo.xsd": "foo" }

• Fails on the first error with a descriptive error message written to standard output

PowerShell script to upload generated XML schemas

The Powershell script uploadschemas.ps1 provides the following features:

• Accepts two command-line parameters:
  • Location of JSON file generated by schema processing tool (XMLSchemaProcessor)
  • API Management resource URL, e.g. https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}
• Acquires Azure access token for current user
• Iterates through schemas in the source JSON file and uploads them to the API Management service using HTTP calls
• Fails on first error

PowerShell script to generate WSDL merged files and upload them to API Management

The Powershell script batchWsdlProcessor.ps1 provides the following features:

• Accepts three command-line parameters:
  • Full path of JSON configuration file with content similar to: {"wsdlFileName.wsdl" : "DirectoryPathOfWsdlFile", ...}
  • API Management resource URL, e.g., https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}
  • WSDLProcessor path, e.g., C:\myPathParent\myPathChild\[...]\Microsoft.Azure.ApiManagement.WsdlProcessor.App.exe
• Acquires Azure access token for current user
• Iterates through JSON configuration file and generates new WSDL files with merged schemas
• Uploads the new WSDL files to the API Management service using HTTP calls
• Fails on first error

PowerShell script to generate new XML schemas and upload them to API Management

The Powershell script batchXmlSchemaProcessor.ps1 provides the following features:

• Accepts three command-line parameters:
  • Full path of JSON configuration file with content similar to: {"inputDirectoryWithSchemas" : "OutputDirectory", ...}
  • API Management resource URL, e.g., https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}
  • XMLSchemaProcessor path, e.g. C:\myPathParent\myPathChild\[...]\Microsoft.Azure.ApiManagement.XmlSchemaProcessor.App.exe
• Acquires Azure access token for current user
• Iterates through JSON configuration file and generates new XML schema files and an upload-plan.json for each
• Uploads the new XML schema files to the API Management service using the upload-plan.json files and HTTP calls
• Fails on first failure

Getting started

Prerequisites

• OS: Windows, Linux, macOS
• .NET 5.0
• .NET CLI
• Azure CLI
• PowerShell

Run WSDLProcessor

1. When you have the .NET CLI installed on your OS of choice, download the code and go to the Microsoft.Azure.ApiManagement.WsdlProcessor.App directory:

    git clone https://github.com/Azure-Samples/api-management-schema-import.git
   
    cd api-management-schema-import/ApiManagementSchemaImport/Microsoft.Azure.ApiManagement.WsdlProcessor.App 
   

2. Restore the packages that are specified in the .csproj file of the project:

    dotnet restore
   

3. Build the project:

    dotnet build
   

   This will drop a binary in ./bin/[configuration]/[net5.0]/[Microsoft.Azure.ApiManagement.WsdlProcessor.App.exe]

4. Run the binary:

    c:\folder\Microsoft.Azure.ApiManagement.WsdlProcessor.App.exe "mywsdlfile.wsdl" "myoutputwsdlfile-processed.wsdl"
   

Run XmlSchemaProcessor

1. When you have the .NET CLI installed on your OS of choice, download the code and go to the Microsoft.Azure.ApiManagement.XmlSchemaProcessor.App directory:

    git clone https://github.com/Azure-Samples/api-management-schema-import.git
   
    cd api-management-schema-import/Mcrosoft.Azure.ApiManagement.XmlSchemaProcessor.App 
   

2. Restore the packages that are specified in the .csproj file of the projecgt:

    dotnet restore
   

3. Build the project:

    dotnet build
   

   This will drop a binary in ./bin/[configuration]/[net5.0]/[Microsoft.Azure.ApiManagement.XmlSchemaProcessor.App.exe]

4. Run the binary:

    c:\folder\Microsoft.Azure.ApiManagement.XmlSchemaProcessor.App.exe "c:\schemaslocation\" "c:\schemaslocation\output\"
   

Powershell UploadSchemas quickstart

.\uploadschemas.ps1 "upload-planLocationFile" "https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}"

Powershell batchWsdlProcessor quickstart

.\batchWsdlProcessor.ps1 "C:\myPathParent\myPathChild\...\wsdlFiles.json" "https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}" "c:\folder\Microsoft.Azure.ApiManagement.WsdlProcessor.App.exe"

Powershell batchXmlSchemaProcessor quickstart

.\batchXmlSchemaProcessor.ps1 "C:\myPathParent\myPathChild\...\xmlSchemaFolders.json" "https://management.azure.com/subscriptions/{subid}/resourceGroups/{rgname}/providers/Microsoft.ApiManagement/service/{servicename}" "c:\folder\Microsoft.Azure.ApiManagement.XmlSchemaProcessor.App.exe"

Resources

• WSDL Schema Files Specification
• API Management REST API
• Validation policies in API Management
• API Management schemas for content validation