Azure Digital Twins Swagger reference documentation
Each provisioned Azure Digital Twins instance includes its own automatically generated Swagger reference documentation.
Swagger, or OpenAPI, unites complex API information into an interactive and language-agnostic reference resource. Swagger provides critical reference material about which JSON payloads, HTTP methods, and specific endpoints to use to perform operations against an API.
Swagger provides an interactive summary of your API, which includes:
- API and object model information.
- REST API endpoints that specify the required request payloads, headers, parameters, context paths, and HTTP methods.
- Testing of API functionalities.
- Example response information used to validate and confirm HTTP responses.
- Error code information.
Swagger is a convenient tool to assist with development and testing calls made to the Azure Digital Twins Management APIs.
A Swagger sneak preview is provided to demonstrate the API feature set. It's hosted at docs.westcentralus.azuresmartspaces.net/management/swagger.
You can access your own generated Management API Swagger documentation at:
|YOUR_INSTANCE_NAME||The name of your Azure Digital Twins instance|
|YOUR_LOCATION||Which server region your instance is hosted on|
The automatically generated Swagger reference material supplies a quick overview of important concepts, available Management API endpoints, and a description of each object model to assist development and testing.
A concise summary describes the API.
Management API object models are also listed.
You can select each listed object model for a more detailed summary of key attributes.
The generated Swagger object models are convenient to read all available Azure Digital Twins objects and APIs. Developers can use this resource when they build solutions on Azure Digital Twins.
Swagger also provides a thorough overview of all endpoints that compose the Management APIs.
Each listed endpoint also includes the required request information, such as the:
- Required parameters.
- Required parameter data types.
- HTTP method to access the resource.
Select each resource to display their additional contents to get a more detailed overview.
Use Swagger to test endpoints
One of the powerful functionalities Swagger provides is the ability to test an API endpoint directly through the documentation UI.
After you select a specific endpoint, the Try it out button will be displayed.
Expand that section to bring up input fields for each required and optional parameter. Enter the correct values, and select Execute.
After you execute the test, you can validate the response data.
Swagger response data
Each listed endpoint also includes response body data to validate your development and tests. These examples include the status codes and JSON for successful HTTP requests.
The examples also include error codes to help debug or improve failing tests.
Swagger OAuth 2.0 authorization
- The user principal that created the Azure Digital Twins resource will have a Space Administrator role assignment and will be able to create additional role assignments for other users. Such users and their roles can be authorized to call the APIs.
Follow the steps in this quickstart to create and configure an Azure AD application. Alternatively, you can reuse an existing app registration.
Add the following Redirect url to your Azure AD app registration:
Name Replace with Example YOUR_SWAGGER_URL Your Management REST API documentation URL found in the portal
Copy the Client ID of your Azure AD app.
After completing the Azure Active Directory registration:
Select the Authorize button on your swagger page.
Paste the application ID into the client_id field.
You will then be redirected to the following success modal.
To learn more about interactively testing requests protected by OAuth 2.0, read the official documentation.