Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@justinyoo
justinyoo committed Apr 14, 2021
1 parent 62865ed commit 81d4039
Show file tree
Hide file tree
Showing 3 changed files with 24 additions and 117 deletions.
2 changes: 2 additions & 0 deletions docs/enable-open-api-endpoints.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ To learn more about Functions costs, see [Estimating Consumption plan costs][az

You have got an Azure Functions app with OpenAPI metadata enabled. In the next articles, you will be able to integrate this OpenAPI-enabled Azure Functions app with either [Azure API Management][az apim], [Azure Logic Apps][az logapp] or [Power Platform][power platform].

* [Configuring OpenAPI Document and Swagger UI Permission and Visibility][docs ui configuration]
* [Customising OpenAPI Document and Swagger UI][docs ui customisation]
* [Support Azure Functions v1 with OpenAPI Extension][docs v1 support]
* [Integrating OpenAPI-enabled Azure Functions to Azure API Management][docs apim]
Expand All @@ -216,6 +217,7 @@ You have got an Azure Functions app with OpenAPI metadata enabled. In the next a
[image-09]: images/image-09.png
[image-10]: images/image-10.png

[docs ui configuration]: openapi.md#Configure-Authorization-Level
[docs ui customisation]: openapi-core.md#OpenAPI-Metadata-Configuration
[docs v1 support]: azure-functions-v1-support.md
[docs apim]: integrate-with-apim.md
Expand Down
8 changes: 4 additions & 4 deletions docs/openapi-core.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,11 @@ Either way, your customised CSS and JavaScript will be applied to the Swagger UI

## OpenAPI Response Header Customisation ##

Often, custom response headers need to be added. You can use `IOpenApiResponseHeaderType` to add the custom response headers.
Often, custom response headers need to be added. You can use `IOpenApiCustomResponseHeader` to add the custom response headers.

```csharp
// Custom response header type
public class CustomResponseHeaderType : IOpenApiResponseHeaderType
public class CustomResponseHeader : IOpenApiCustomResponseHeader
{
public Dictionary<string, OpenApiHeader> Headers { get; set; } =
new Dictionary<string, OpenApiHeader>()
Expand All @@ -214,8 +214,8 @@ public static class CustomResponseHeaderHttpTrigger
{
[FunctionName(nameof(CustomResponseHeaderHttpTrigger))]
...
[OpenApiResponseWithBody(... HeaderType = typeof(CustomResponseHeaderType))]
[OpenApiResponseWithoutBody(... HeaderType = typeof(CustomResponseHeaderType))]
[OpenApiResponseWithBody(... HeaderType = typeof(CustomResponseHeader))]
[OpenApiResponseWithoutBody(... HeaderType = typeof(CustomResponseHeader))]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Function, "GET", Route = null)] HttpRequest req,
ILogger log)
Expand Down
131 changes: 18 additions & 113 deletions docs/openapi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,131 +19,36 @@ While using this library, if you find any issue, please raise a ticket on the [I

## Getting Started ##

### Install NuGet Package ###
For detailed getting started document, find this [Enable OpenAPI Endpoints on Azure Functions (Preview)](enable-open-api-endpoints.md) page.

In order for your Azure Functions app to enable OpenAPI capability, download the following NuGet package into your Azure Functions project.

```bash
dotnet add <PROJECT> package Microsoft.Azure.WebJobs.Extensions.OpenApi
```


### Change Authorization Level ###

As a default, all endpoints to render Swagger UI and OpenAPI documents have the authorisation level of `AuthorizationLevel.Anonymous`.


```csharp
[FunctionName(nameof(OpenApiHttpTrigger.RenderSwaggerDocument))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderSwaggerDocument(
[HttpTrigger(AuthorizationLevel.Anonymous, "GET", Route = "swagger.{extension}")] HttpRequest req,
string extension,
ILogger log)
{
...
}
### Configure Authorization Level ###

[FunctionName(nameof(OpenApiHttpTrigger.RenderOpenApiDocument))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderOpenApiDocument(
[HttpTrigger(AuthorizationLevel.Anonymous, "GET", Route = "openapi/{version}.{extension}")] HttpRequest req,
string version,
string extension,
ILogger log)
{
...
}
As a default, all endpoints to render Swagger UI and OpenAPI documents have the authorisation level of `AuthorizationLevel.Anonymous`. However, if you want to secure those endpoints, change their authorisation level to `AuthorizationLevel.Functions` and pass the API Key through either request header or querystring parameter. This can be done through the environment variables. Here's the sample `local.settings.json` file. The other values are omitted for brevity.

[FunctionName(nameof(OpenApiHttpTrigger.RenderSwaggerUI))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderSwaggerUI(
[HttpTrigger(AuthorizationLevel.Anonymous, "GET", Route = "swagger/ui")] HttpRequest req,
ILogger log)
```json
{
...
"Values": {
"OpenApi__ApiKey": "",
"OpenApi__AuthLevel__Document": "Anonymous",
"OpenApi__AuthLevel__UI": "Anonymous"
}
}
```

However, if you want to secure those endpoints, change their authorisation level to `AuthorizationLevel.Functions` and pass the API Key through either request header or querystring parameter.

> **NOTE**: To change this authorisation level, you MUST install the `Microsoft.Azure.WebJobs.Extensions.OpenApi.Core` package, instead of `Microsoft.Azure.WebJobs.Extensions.OpenApi`, and copy those three files from the source codes to your application:
>
> * `templates/OpenApiEndpoints/IOpenApiHttpTriggerContext.cs`
> * `templates/OpenApiEndpoints/OpenApiHttpTrigger.cs`
> * `templates/OpenApiEndpoints/OpenApiHttpTriggerContext.cs`
```csharp
[FunctionName(nameof(OpenApiHttpTrigger.RenderSwaggerDocument))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderSwaggerDocument(
[HttpTrigger(AuthorizationLevel.Function, "GET", Route = "swagger.{extension}")] HttpRequest req,
string extension,
ILogger log)
{
...
}
You can have granular controls to both Swagger UI and OpenAPI documents by setting the authorisation level to `Anonymous`, `User`, `Function`, `System` or `Admin`. Make sure that you MUST provide the `OpenApi_AuthKey` value, if you choose the `OpenApi__AuthLevel__Document` value other than `Anonymous`. Otherwise, it will throw an error. Both Swagger UI and OpenAPI document pages are allowed `Anonymous` access by default.

[FunctionName(nameof(OpenApiHttpTrigger.RenderOpenApiDocument))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderOpenApiDocument(
[HttpTrigger(AuthorizationLevel.Function, "GET", Route = "openapi/{version}.{extension}")] HttpRequest req,
string version,
string extension,
ILogger log)
{
...
}

[FunctionName(nameof(OpenApiHttpTrigger.RenderSwaggerUI))]
[OpenApiIgnore]
public static async Task<IActionResult> RenderSwaggerUI(
[HttpTrigger(AuthorizationLevel.Function, "GET", Route = "swagger/ui")] HttpRequest req,
ILogger log)
{
...
}
```


### Configure App Settings Key ###

This key is only required if:

* The Function app is deployed to Azure, and
* The OpenAPI related endpoints has the `AuthorizationLevel` value other than `Anonymous`.
### Configure Swagger UI Visibility ###

If the above conditions are met, add the following key to your `local.settings.json` or App Settings blade on Azure.
You may want to only enable the Swagger UI page during the development time, and disable the page when publishing it to Azure. You can configure an environment variable to enable/disable the Swagger UI page. Here's the sample `local.settings.json` file. The other values are omitted for brevity.

* `OpenApi__ApiKey`: either the host key value or the master key value.

> **NOTE**: It is NOT required if your OpenAPI related endpoints are set to the authorisation level of `Anonymous`.

## OpenAPI Metadata Configuration ##

To generate an OpenAPI document, [OpenApiInfo object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject) needs to be defined. ***It's totally optional***, but if you want, you can implement the `IOpenApiConfigurationOptions` interface within your Azure Functions project to provide OpenAPI metadata like below:

```csharp
public class OpenApiConfigurationOptions : IOpenApiConfigurationOptions
```json
{
public OpenApiInfo Info { get; set; } = new OpenApiInfo()
{
Version = "1.0.0",
Title = "OpenAPI Document on Azure Functions",
Description = "HTTP APIs that run on Azure Functions using OpenAPI specification.",
TermsOfService = new Uri("https://github.com/Azure/azure-functions-openapi-extension"),
Contact = new OpenApiContact()
{
Name = "Contoso",
Email = "azfunc-openapi@contoso.com",
Url = new Uri("https://github.com/Azure/azure-functions-openapi-extension/issues"),
},
License = new OpenApiLicense()
{
Name = "MIT",
Url = new Uri("http://opensource.org/licenses/MIT"),
}
};
"Values": {
"OpenApi__HideSwaggerUI": "false"
}
}
```

If you set the `OpenApi__HideSwaggerUI` value to `true`, the Swagger UI page won't be showing up, and you will see the 404 error. The default value is `false`.

0 comments on commit 81d4039

Please sign in to comment.