Add a HideDocument flag akin to HideSwaggerUI

[gsteenpa]

Added a flag to hide the document bindings so that the feature can be "turned off" in a particular configuration of a deployed API.

Setting HideDocument will also hide the UI.

[ghost]

All CLA requirements met.

[justinyoo]

@gsteenpa Thanks for the PR!

But, would you please be able to elaborate this PR? If you hide the OpenAPI document, what's the purpose of using this extension?

[gsteenpa]

@gsteenpa Thanks for the PR!

But, would you please be able to elaborate this PR? If you hide the OpenAPI document, what's the purpose of using this extension?

Hi @justinyoo - If you want to use same code build in every environment, but not have the swagger documentation available in every environment, this flag lets you do that via configuration. For example, we use the json to generate api clients in the build pipeline and have the ui /json available in Dev, but off/blocked everywhere else.

[justinyoo]

Hi @justinyoo - If you want to use same code build in every environment, but not have the swagger documentation available in every environment, this flag lets you do that via configuration. For example, we use the json to generate api clients in the build pipeline and have the ui /json available in Dev, but off/blocked everywhere else.

Then, I would recommend modifying your .csproj file to conditionally add this package. You can achieve this like:

<Project ...>
  <PropertyGroup>
    ...
    <OpenApiExtensionRequired>True</OpenApiExtensionRequired>
  </PropertyGroup>

  <ItemGroup Condition="'$(OpenApiExtensionRequired)'=='True'">
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.OpenApi" Version="0.9.0-preview" />
  </ItemGroup>
  ...
</Project>

Then, within your release pipeline for environments other than DEV, publish your app like:

dotnet publish FunctionApp.csproj ... /p:OpenApiExtensionRequired=False

That could be much easier, without having to touch codes.

[gsteenpa]

Hi @justinyoo - If you want to use same code build in every environment, but not have the swagger documentation available in every environment, this flag lets you do that via configuration. For example, we use the json to generate api clients in the build pipeline and have the ui /json available in Dev, but off/blocked everywhere else.

Then, I would recommend modifying your .csproj file to conditionally add this package. You can achieve this like:

<Project ...>
  <PropertyGroup>
    ...
    <OpenApiExtensionRequired>True</OpenApiExtensionRequired>
  </PropertyGroup>

  <ItemGroup Condition="'$(OpenApiExtensionRequired)'=='True'">
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.OpenApi" Version="0.9.0-preview" />
  </ItemGroup>
  ...
</Project>

Then, within your release pipeline for environments other than DEV, publish your app like:

dotnet publish FunctionApp.csproj ... /p:OpenApiExtensionRequired=False

That could be much easier, without having to touch codes.

Thank you for the suggestion, but changing a configuration flag would be much easier than changing the referenced DLLs for us. We deploy via zip file and want to use the same zip file in every environment. We leverage configuration flags to alter the behavior of that deployed code via keyvault secrets. Using the publish parameter would require us to deploy different zip files to different environments which we would like to avoid.

[justinyoo]

Thanks for the clarification. I'm still not 100% convinced whether this is the proper approach or not. Let me take a further look.

[justinyoo]

I took a look and have one ask for your to consider.

Because Swagger UI without OpenAPI document can't render the UI page properly, the HideDocument flag is set to true, it should also hide the UI page, regardless of the HideSwaggerUI value being true or false. Therefore, the logic between these two flags should be like below:

HideSwaggerUI	HideDocument	Swagger UI	OpenAPI Document
false	false	SHOW	SHOW
false	true	ERROR 👈 (current)	NO SHOW
false	true	NO SHOW 👈 (to be)	NO SHOW
true	false	NO SHOW	SHOW
true	true	NO SHOW	NO SHOW

[gsteenpa]

I took a look and have one ask for your to consider.

Because Swagger UI without OpenAPI document can't render the UI page properly, the HideDocument flag is set to true, it should also hide the UI page, regardless of the HideSwaggerUI value being true or false. Therefore, the logic between these two flags should be like below:

HideSwaggerUI HideDocument Swagger UI OpenAPI Document
false false SHOW SHOW
false true ERROR 👈 (current) NO SHOW
false true NO SHOW 👈 (to be) NO SHOW
true false NO SHOW SHOW
true true NO SHOW NO SHOW

All set.

[justinyoo]

Thanks for the long wait! I've left a couple of comments for your to take a look - both are to avoid additonal indentation depth.

[justinyoo]

LGTM! Thanks for the wait!