ALOps OpenAPI¶

Generate OpenAPI descriptions from Business Central API's.

Property	Value
Task name (Azure DevOps)	`ALOpsOpenAPI@3`
Action name (GitHub)	`alops-openapi`
Version	`3.0.0`
Category	Utility
OS requirement	Both
Preview	yes

Generate OpenAPI 3.0 specifications from Business Central APIs. Supports automatic route discovery, manual route selection, and export to EDMX, JSON, and YAML formats. Authenticate via OAuth2 (client credentials or client certificate), basic auth, Windows integrated auth, or username/password.

Inputs¶

authentication¶

Name	Type	Required	Default	Platform	Description
`authentication`	PickList	yes	`oauth`	Both	Authentication method for the API connection. oauth uses Azure AD service-to-service tokens (recommended for SaaS). basic and usernamepassword use user credentials. windows uses Windows integrated authentication (on-premises only). Options: `basic`, `oauth`, `windows`, `usernamepassword`.
`azure_tenant_id`	Text	no	(empty)	Both	Azure Active Directory tenant ID (GUID or domain) of the Business Central SaaS tenant.
`azure_app_client_id`	Text	no	(empty)	Both	Application (client) ID of the Azure AD app registration used for OAuth authentication.
`azure_app_client_secret`	Secret	no	(empty)	Both	Client secret of the Azure AD app registration. Store this value in a pipeline secret variable or Azure Key Vault, never in plain text.
`azure_app_client_certificate`	Text	no	(empty)	Both	Path, base-64 encoded content, or certificate store reference (CERT:...) of the certificate (.pfx) used instead of a client secret for Azure AD app authentication.
`azure_app_client_certificate_password`	Secret	no	(empty)	Both	Password protecting the client certificate. Store this in a pipeline secret variable.
`username`	Text	no	(empty)	Both	Business Central user account name. Used for basic or usernamepassword authentication.
`password`	Secret	no	(empty)	Both	Password for the Business Central user account. Store this in a pipeline secret variable.

docker¶

Name	Type	Required	Default	Platform	Description
`usedocker`	Boolean	no	`false`	Both	Run the OpenAPI generation inside a Docker container instead of the host agent.
`fixed_tag`	Text	no	(empty)	Both	Fixed tag to identify the Docker container. When empty, the build label is used.

discovery¶

Name	Type	Required	Default	Platform	Description
`discover`	Boolean	no	`true`	Both	Automatically discover available API routes from the Business Central runtime API.
`api_routes`	MultiLine	no	(empty)	Both	Manual list of API routes to convert (one per line or pipe-delimited). Used when discover is false.
`api_exclude_routes`	MultiLine	no	(empty)	Both	Routes to exclude from automatic discovery (one per line or pipe-delimited).
`inspect_paths`	Boolean	no	`false`	Both	Print all discovered API paths for each route to the build log.

export¶

Name	Type	Required	Default	Platform	Description
`api_servers`	MultiLine	no	(empty)	Both	Custom server URLs to include in the OpenAPI specification (one per line or pipe-delimited). When empty, the original API endpoint is used.
`export_edmx`	Boolean	no	`false`	Both	Export the raw EDMX metadata alongside the OpenAPI specification.
`export_yaml`	Boolean	no	`true`	Both	Export the OpenAPI specification in YAML format.
`export_json`	Boolean	no	`false`	Both	Export the OpenAPI specification in JSON format.
`publish_artifacts`	Boolean	no	`true` (alt: `true`)	Azure DevOps only	Upload the generated OpenAPI files as build artifacts.

filtering¶

Name	Type	Required	Default	Platform	Description
`exclude_company_paths`	Boolean	no	`false`	Both	Exclude company-scoped paths from the OpenAPI specification. When enabled, a company header parameter is added instead.

General¶

Name	Type	Required	Default	Platform	Description
`api_endpoint`	Text	yes	`https://api.businesscentral.dynamics.com/v2.0/$(azure_tenant_id)/Sandbox/api`	Both	Base URL of the Business Central API. Use $(azure_tenant_id) as a placeholder — it is replaced at runtime with the azure_tenant_id input value.

Usage¶

Azure DevOpsGitHub Actions

- task: ALOpsOpenAPI@3
  displayName: 'ALOps OpenAPI'
  inputs:
    api_endpoint: https://api.businesscentral.dynamics.com/v2.0/$(azure_tenant_id)/Sandbox/api  # Base URL of the Business Central API. Use $(azure_tenant_id) as a placeholder — it is replaced at runtime with the azure_tenant_id input value. $(api_endpoint)
    authentication: oauth                                                                       # Authentication method for the API connection. oauth uses Azure AD service-to-service tokens (recommended for SaaS). basic and usernamepassword use user credentials. windows uses Windows integrated authentication (on-premises only). $(authentication)
    azure_tenant_id:                                                                            # Azure Active Directory tenant ID (GUID or domain) of the Business Central SaaS tenant. $(azure_tenant_id)
    azure_app_client_id:                                                                        # Application (client) ID of the Azure AD app registration used for OAuth authentication. $(azure_app_client_id)
    azure_app_client_secret:                                                                    # Client secret of the Azure AD app registration. Store this value in a pipeline secret variable or Azure Key Vault, never in plain text. $(azure_app_client_secret)
    azure_app_client_certificate:                                                               # Path, base-64 encoded content, or certificate store reference (CERT:\...) of the certificate (.pfx) used instead of a client secret for Azure AD app authentication. $(azure_app_client_certificate)
    azure_app_client_certificate_password:                                                      # Password protecting the client certificate. Store this in a pipeline secret variable. $(azure_app_client_certificate_password)
    username:                                                                                   # Business Central user account name. Used for basic or usernamepassword authentication. $(username)
    password:                                                                                   # Password for the Business Central user account. Store this in a pipeline secret variable. $(password)
    usedocker: False                                                                            # Run the OpenAPI generation inside a Docker container instead of the host agent. $(usedocker)
    fixed_tag:                                                                                  # Fixed tag to identify the Docker container. When empty, the build label is used. $(fixed_tag)
    discover: True                                                                              # Automatically discover available API routes from the Business Central runtime API. $(discover)
    api_routes:                                                                                 # Manual list of API routes to convert (one per line or pipe-delimited). Used when discover is false. $(api_routes)
    api_exclude_routes:                                                                         # Routes to exclude from automatic discovery (one per line or pipe-delimited). $(api_exclude_routes)
    inspect_paths: False                                                                        # Print all discovered API paths for each route to the build log. $(inspect_paths)
    api_servers:                                                                                # Custom server URLs to include in the OpenAPI specification (one per line or pipe-delimited). When empty, the original API endpoint is used. $(api_servers)
    export_edmx: False                                                                          # Export the raw EDMX metadata alongside the OpenAPI specification. $(export_edmx)
    export_yaml: True                                                                           # Export the OpenAPI specification in YAML format. $(export_yaml)
    export_json: False                                                                          # Export the OpenAPI specification in JSON format. $(export_json)
    publish_artifacts: True                                                                     # Upload the generated OpenAPI files as build artifacts. $(publish_artifacts)
    exclude_company_paths: False                                                                # Exclude company-scoped paths from the OpenAPI specification. When enabled, a company header parameter is added instead. $(exclude_company_paths)

- name: ALOps OpenAPI
  uses: HodorNV/ALOps-V3/alops-openapi@v3   <!-- TODO: confirm action repo path -->
  with:
    api_endpoint: 'https://api.businesscentral.dynamics.com/v2.0/$(azure_tenant_id)/Sandbox/api'
    authentication: 'oauth'
    azure_tenant_id: ''
    azure_app_client_id: ''
    azure_app_client_secret: ''
    azure_app_client_certificate: ''
    azure_app_client_certificate_password: ''
    username: ''
    password: ''
    usedocker: 'false'
    fixed_tag: ''
    discover: 'true'
    api_routes: ''
    api_exclude_routes: ''
    inspect_paths: 'false'
    api_servers: ''
    export_edmx: 'false'
    export_yaml: 'true'
    export_json: 'false'
    exclude_company_paths: 'false'