"offline" generation of OpenAPI definition for use in build pipeline

[filcole]

When working with a solution containing a PowerPlatform custom connector that uses an OpenAPI definition generated from an Azure Function it would be good to be able to output the OpenAPI definition (v2 currently only for custom connectors) within a build pipeline.

This would remove the manual step of having to update the custom connector YAML, then export the solution containing the custom connector.

[justinyoo]

@filcole Did you mean the CLI version of it? Could you please elaborate a bit more?

[filcole]

Hi @justinyoo,

Yes something like the CLI version from the Aliencube repo - so that a build process can "compile" and generate an OpenAPI definition which can then be included in the "source" for a PowerPlatform custom connector. Custom connectors in PowerPlatform solutions can be exploded into individual files using the solutionpackager.exe tool. Each custom connector has it's own directory which contains five files:

• .xml <- the metadata for the connector used by the solution
• _connectionparameters.xml
• _iconblob.png <- the custom connector icon
• _openapidefinition.json <- this appears to be a OpenAPI v2 definition we can replace by the CLI generated version
• _policytemplate.json <- policy template used when a connection is used/made.

At the moment the Azure Functions OpenAPI extension forces us to publish to Azure before being able to download an OpenAPI definition. Ideally, this should be done at build time, especially when managed solutions in the power platform are used (as MS recommend these days).

[sonic1981]

Yes, I wanted to really publish my open api separate to my functions but I can't currently as the json is built on the fly. I'd prefer if the json could be built by my deployment pipeline and then deployed to a web app separate to my function apps. Not least of which because of security.

It'd also be nice to specify multiple endpoints in one Open API doc. I've done this in a custom build. I have 4 different functions in different zones that are identical so it'd make sense for me to have one swagger, not 4

[svrooij]

This would serve multiple purposes:

1. Generating at build time (and serving a static json file) is probably faster then generating it at runtime every time api/openapi/v2.json is called.
2. If this file is available at build time we could use NSwag to generate strong typed clients (C# or TypeScript), which could then also be published some where.

The last use case for us it that we have this Azure Functions api and a accompaning Angular SPA. The services classes in this Angular SPA are strong typed based on the openapi specifications. So if we change something in the api, a single build (in debug mode) would be enough to also automatically update the services in the TypeScript application.

[justinyoo]

Related to: aliencube/AzureFunctions.Extensions#132

[justinyoo]

Related to: aliencube/AzureFunctions.Extensions#126

[sabryguen]

Hey @justinyoo, is there an ETA on this feature? I have similar demand for generating a swagger.json file as part of the build pipeline.

Can you think of any workarounds for the time being?

Thanks,

Sabry

[jeromekol]

Hey @justinyoo, is there an ETA on this feature? I have similar demand for generating a swagger.json file as part of the build pipeline.

Can you think of any workarounds for the time being?

Thanks,

Sabry

Bit late, but I've been using the code that is in the CLI folder on this repo: https://github.com/Azure/azure-functions-openapi-extension/blob/main/src/Microsoft.Azure.WebJobs.Extensions.OpenApi.CLI/Program.cs

Maybe that helps someone else.

[justinyoo]

As the PR, #489, has been merged, you can generate the OpenAPI doc on-the-fly, within the GitHub Actions workflow.