Azure / Azure/azure-functions-openapi-extension

New Feature: Expose UI endpoints to APIM by devs' choice

Open
#403 2 comments 1 reaction 0 assignees View on GitHub
documentation enhancement
Dominant language
C#
Stars
388
Forks
202
PR merge metrics
No merged PRs in 30d

Description

Curerntly, 4 UI-related endpoints are not exposed to the OpenAPI document:

* `/swagger/ui`
* `/swagger.{extension}`
* `/openapi/{version}.{extension}`
* `/oauth2-redirect.html`

There are cases that devs want to expose those endpoints through Azure APIM. In that case, they have to manually add them. To reduce this manual efforts, this feature would be useful:

1. Add the environment variable `OpenApi__ExposeUI` – its value will be `false` by default. If it's set to `true`, all four UI-related endpoints should be accessible through APIM.
2. Add the querystring parameter `exposeui` – itsvalue will be `false` by default. If it's set to `true`, all four UI-related endpoints should be accessible through APIM. In addition to that, this querystring parameter should take precedense to the environment variable.

---
Update: 2022-03-29

There have already been options – `OpenApi__HideSwaggerUI` and `OpenApi__HideDocument` that are applicable on the function app levels. To avoid providing dev with misleading information, the environment variable names might be changed.

Contributor guide

Open the contributing guide

Research direction

Start by locating the routing for `/swagger/ui`, `/swagger.{extension}`, `/openapi/{version}.{extension}`, and `/oauth2-redirect.html`, then inspect how `OpenApi__HideSwaggerUI` and `OpenApi__HideDocument` are applied. Define the precedence between the `exposeui` query parameter and `OpenApi__ExposeUI`, and verify that all four endpoints are exposed only when the effective value is true.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, csharp, openapi
Domain
api, cloud
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.