|
| 1 | +# Aliencube.AzureFunctions.Extensions.OpenApi.Core # |
| 2 | + |
| 3 | + [](https://www.nuget.org/packages/Aliencube.AzureFunctions.Extensions.OpenApi.Core/) [](https://www.nuget.org/packages/Aliencube.AzureFunctions.Extensions.OpenApi.Core/) |
| 4 | + |
| 5 | +This enables Azure Functions to render Open API document and Swagger UI. The more details around the Swagger UI on Azure Functions can be found on this [blog post](https://devkimchi.com/2019/02/02/introducing-swagger-ui-on-azure-functions/). |
| 6 | + |
| 7 | +> **NOTE**: This extension supports both [Open API 2.0 (aka Swagger)](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) and [Open API 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md) spec. |
| 8 | +
|
| 9 | + |
| 10 | +## Acknowledgement ## |
| 11 | + |
| 12 | +* In order to read JSON configuration on Azure Functions 1.x, these extensions have copied the source code of [Microsoft.Extensions.Configuration.Json](https://github.com/aspnet/Extensions/tree/master/src/Configuration/Config.Json) to make use of [Newtonsoft.Json 9.0.1](https://www.nuget.org/packages/Newtonsoft.Json/9.0.1) under the [MIT License](http://opensource.org/licenses/MIT). |
| 13 | +* [Swagger UI](https://github.com/swagger-api/swagger-ui) version used for this library is [3.20.5](https://github.com/swagger-api/swagger-ui/releases/tag/v3.20.5) under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0). |
| 14 | + |
| 15 | + |
| 16 | +## Issues? ## |
| 17 | + |
| 18 | +While using this library, if you find any issue, please raise a ticket on the [Issue](https://github.com/aliencube/AzureFunctions.Extensions/issues) page. |
| 19 | + |
| 20 | + |
| 21 | +## Getting Started ## |
| 22 | + |
| 23 | +### Install NuGet Package ### |
| 24 | + |
| 25 | +In order for your Azure Functions app to enable Open API capability, download the following NuGet package into your Azure Functions project. |
| 26 | + |
| 27 | +```bash |
| 28 | +dotnet add <PROJECT> package Aliencube.AzureFunctions.Extensions.OpenApi.Core |
| 29 | +``` |
| 30 | + |
| 31 | + |
| 32 | +### Expose Endpoints to Open API Document ### |
| 33 | + |
| 34 | +In order to include HTTP endpoints into the Open API document, use attribute classes (decorators) like: |
| 35 | + |
| 36 | +```csharp |
| 37 | +[FunctionName(nameof(AddDummy))] |
| 38 | +[OpenApiOperation("addDummy", "dummy")] |
| 39 | +[OpenApiRequestBody("application/json", typeof(DummyRequestModel))] |
| 40 | +[OpenApiResponseBody(HttpStatusCode.OK, "application/json", typeof(DummyResponseModel))] |
| 41 | +public static async Task<IActionResult> AddDummy( |
| 42 | + [HttpTrigger(AuthorizationLevel.Function, "post", Route = "dummies")] HttpRequest req, |
| 43 | + ILogger log) |
| 44 | +{ |
| 45 | + ... |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | + |
| 50 | +### Configure App Settings Key ### |
| 51 | + |
| 52 | +This key is only required if: |
| 53 | + |
| 54 | +* The Function app is deployed to Azure, and |
| 55 | +* The Open API related endpoints has the `AuthorizationLevel` value other than `Anonymous`. |
| 56 | + |
| 57 | +If the above conditions are met, add the following key to your `locall.settings.json` or App Settings blade on Azure. |
| 58 | + |
| 59 | +* `OpenApi__ApiKey`: either the host key value or the master key value. |
| 60 | + |
| 61 | +> **NOTE**: It is NOT required if your Open API related endpoints are set to the authorisation level of `Anonymous`. |
| 62 | +
|
| 63 | + |
| 64 | +## Open API Metadata Configuration ## |
| 65 | + |
| 66 | +To generate an Open API document, [OpenApiInfo object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject) needs to be defined. This information can be declared in **ONE OF THREE** places – `host.json`, `openapisettings.json` or `local.settings.json`. |
| 67 | + |
| 68 | +This library looks for the information in the following order: |
| 69 | + |
| 70 | +1. `host.json` |
| 71 | +2. `openapisettings.json` |
| 72 | +3. `local.settings.json` or App Settings blade on Azure |
| 73 | + |
| 74 | + |
| 75 | +### `host.json` ### |
| 76 | + |
| 77 | +Although it has not been officially accepted to be a part of `host.json`, the Open API metadata still can be stored in it like: |
| 78 | + |
| 79 | +```json |
| 80 | +{ |
| 81 | + ... |
| 82 | + "openApi": { |
| 83 | + "info": { |
| 84 | + "version": "1.0.0", |
| 85 | + "title": "Open API Sample on Azure Functions", |
| 86 | + "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from **host. json**.", |
| 87 | + "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions", |
| 88 | + "contact": { |
| 89 | + "name": "Aliencube Community", |
| 90 | + |
| 91 | + "url": "https://github.com/aliencube/AzureFunctions.Extensions/issues" |
| 92 | + }, |
| 93 | + "license": { |
| 94 | + "name": "MIT", |
| 95 | + "url": "http://opensource.org/licenses/MIT" |
| 96 | + } |
| 97 | + } |
| 98 | + } |
| 99 | + ... |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | + |
| 104 | +### `openapisettings.json` ### |
| 105 | + |
| 106 | +The Open API metadata can be defined in a separate file, `openapisettings.json` like: |
| 107 | + |
| 108 | +```json |
| 109 | +{ |
| 110 | + "info": { |
| 111 | + "version": "1.0.0", |
| 112 | + "title": "Open API Sample on Azure Functions", |
| 113 | + "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from **openapisettings.json**.", |
| 114 | + "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions", |
| 115 | + "contact": { |
| 116 | + "name": "Aliencube Community", |
| 117 | + |
| 118 | + "url": "https://github.com/aliencube/AzureFunctions.Extensions/issues" |
| 119 | + }, |
| 120 | + "license": { |
| 121 | + "name": "MIT", |
| 122 | + "url": "http://opensource.org/licenses/MIT" |
| 123 | + } |
| 124 | + } |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | + |
| 129 | +### `local.settings.json` or App Settings Blade ### |
| 130 | + |
| 131 | +On either your `local.settings.json` or App Settings on Azure Functions instance, those details can be set up like: |
| 132 | + |
| 133 | +* `OpenApi__Info__Version`: **REQUIRED** Version of Open API document. This is not the version of Open API spec. eg. 1.0.0 |
| 134 | +* `OpenApi__Info__Title`: **REQUIRED** Title of Open API document. eg. Open API Sample on Azure Functions |
| 135 | +* `OpenApi__Info__Description`: Description of Open API document. eg. A sample API that runs on Azure Functions either 1.x or 2.x using Open API specification. |
| 136 | +* `OpenApi__Info__TermsOfService`: Terms of service URL. eg. https://github.com/aliencube/AzureFunctions.Extensions |
| 137 | +* `OpenApi__Info__Contact__Name`: Name of contact. eg. Aliencube Community |
| 138 | +* `OpenApi__Info__Contact__Email`: Email address for the contact. eg. [email protected] |
| 139 | +* `OpenApi__Info__Contact__Url`: Contact URL. eg. https://github.com/aliencube/AzureFunctions.Extensions/issues |
| 140 | +* `OpenApi__Info__License__Name`: **REQUIRED** License name. eg. MIT |
| 141 | +* `OpenApi__Info__License__Url`: License URL. eg. http://opensource.org/licenses/MIT |
| 142 | + |
| 143 | +> **NOTE**: In order to deploy Azure Functions v1 to Azure, the `AzureWebJobsScriptRoot` **MUST** be specified in the app settings section; otherwise it will throw an error that can't find `host.json`. Local debugging is fine, though. For more details, please visit [this page](https://docs.microsoft.com/azure/azure-functions/functions-app-settings#azurewebjobsscriptroot?WT.mc_id=azfuncextension-github-juyoo). |
| 144 | +
|
| 145 | + |
| 146 | +## Decorators ## |
| 147 | + |
| 148 | +In order to render Open API document, this uses attribute classes (decorators). |
| 149 | + |
| 150 | +> **NOTE**: Not all Open API specs have been implemented. |
| 151 | +
|
| 152 | + |
| 153 | +### `OpenApiIgnoreAttribute` ### |
| 154 | + |
| 155 | +If there is any HTTP trigger that you want to exclude from the Open API document, use this decorator. Typically this is used for the endpoints that render Open API document and Swagger UI. |
| 156 | + |
| 157 | +```csharp |
| 158 | +[FunctionName(nameof(RenderSwaggerDocument))] |
| 159 | +[OpenApiIgnore] // This HTTP endpoint is excluded from the Open API document. |
| 160 | +public static async Task<IActionResult> RenderSwaggerDocument( |
| 161 | + [HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger.{extension}")] HttpRequest req, |
| 162 | + string extension, |
| 163 | + ILogger log) |
| 164 | +{ |
| 165 | + ... |
| 166 | +} |
| 167 | +``` |
| 168 | + |
| 169 | + |
| 170 | +### `OpenApiOperationAttribute` ### |
| 171 | + |
| 172 | +This decorator implements a part of [Operation object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject) spec. |
| 173 | + |
| 174 | +```csharp |
| 175 | +[FunctionName(nameof(GetSample))] |
| 176 | +[OpenApiOperation(operationId: "list", tags: new[] { "sample" })] |
| 177 | +... |
| 178 | +public static async Task<IActionResult> GetSample( |
| 179 | + [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "samples")] HttpRequest req, |
| 180 | + ILogger log) |
| 181 | +{ |
| 182 | + ... |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +* `OperationId`: is the ID of the operation. If this is omitted, a combination of function name and verb is considered as the operation ID. eg) `Get_GetSample` |
| 187 | +* `Tags`: are the list of tags of operation. |
| 188 | +* `Summary`: is the summary of the operation. |
| 189 | +* `Description`: is the description of the operation. |
| 190 | +* `Visibility`: indicates how the operation is visible in Azure Logic Apps – `important`, `advanced` or `internal`. Default value is `undefined`. |
| 191 | + |
| 192 | + |
| 193 | +### `OpenApiParameterAttribute` ### |
| 194 | + |
| 195 | +This decorator implements the [Parameter object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject) spec. |
| 196 | + |
| 197 | +```csharp |
| 198 | +[FunctionName(nameof(GetSample))] |
| 199 | +[OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = true, Type = typeof(string))] |
| 200 | +... |
| 201 | +public static async Task<IActionResult> GetSample( |
| 202 | + [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "samples")] HttpRequest req, |
| 203 | + ILogger log) |
| 204 | +{ |
| 205 | + ... |
| 206 | +} |
| 207 | +``` |
| 208 | + |
| 209 | +* `Name`: is the name of the parameter. |
| 210 | +* `Summary`: is the summary of the parameter. |
| 211 | +* `Description`: is the description of the parameter. |
| 212 | +* `Type`: defines the parameter type. Default value is `typeof(string)`. |
| 213 | +* `In`: identifies where the parameter is located – `header`, `path`, `query` or `cookie`. Default value is `path`. |
| 214 | +* `CollectionDelimiter`: identifies the delimiter when a query parameter accepts multiple values – `comma`, `space` or `pipe`. Default value is `comma`. |
| 215 | +* `Explode`: indicates whether a query parameter is used multiple times (eg. `foo=bar1&foo=bar2&foo=bar3`) or not (eg. `foo=bar1,bar2,bar3`). Default value is `false`. |
| 216 | +* `Required`: indicates whether the parameter is required or not. Default value is `false`. |
| 217 | +* `Visibility`: indicates how the parameter is visible in Azure Logic Apps – `important`, `advanced` or `internal`. Default value is `undefined`. |
| 218 | + |
| 219 | + |
| 220 | +### `OpenApiRequestBodyAttribute` ### |
| 221 | + |
| 222 | +This decorator implements the [Request Body object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#requestBodyObject) spec. |
| 223 | + |
| 224 | +```csharp |
| 225 | +[FunctionName(nameof(PostSample))] |
| 226 | +[OpenApiRequestBody(contentType: "application/json", bodyType: typeof(SampleRequestModel))] |
| 227 | +... |
| 228 | +public static async Task<IActionResult> PostSample( |
| 229 | + [HttpTrigger(AuthorizationLevel.Function, "post", Route = "samples")] HttpRequest req, |
| 230 | + ILogger log) |
| 231 | +{ |
| 232 | + ... |
| 233 | +} |
| 234 | +``` |
| 235 | + |
| 236 | +* `ContentType`: defines the content type of the request body payload. eg) `application/json` or `text/xml` |
| 237 | +* `BodyType`: defines the type of the request payload. |
| 238 | +* `Summary`: is the summary of the request payload. |
| 239 | +* `Description`: is the description of the request payload. |
| 240 | +* `Required`: indicates whether the request payload is mandatory or not. |
| 241 | + |
| 242 | + |
| 243 | +### `OpenApiResponseWithBodyAttribute` ### |
| 244 | + |
| 245 | +This decorator implements the [Response object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#responseObject) spec. |
| 246 | + |
| 247 | +```csharp |
| 248 | +[FunctionName(nameof(PostSample))] |
| 249 | +[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(SampleResponseModel))] |
| 250 | +... |
| 251 | +public static async Task<IActionResult> PostSample( |
| 252 | + [HttpTrigger(AuthorizationLevel.Function, "post", Route = "samples")] HttpRequest req, |
| 253 | + ILogger log) |
| 254 | +{ |
| 255 | + ... |
| 256 | +} |
| 257 | +``` |
| 258 | + |
| 259 | +* `StatusCode`: defines the HTTP status code. eg) `HttpStatusCode.OK` |
| 260 | +* `ContentType`: defines the content type of the response payload. eg) `application/json` or `text/xml` |
| 261 | +* `BodyType`: defines the type of the response payload. |
| 262 | +* `Summary`: is the summary of the response. |
| 263 | +* `Description`: is the description of the response. |
| 264 | + |
| 265 | + |
| 266 | +### `OpenApiResponseWithoutBodyAttribute` ### |
| 267 | + |
| 268 | +This decorator implements the [Response object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#responseObject) spec. |
| 269 | + |
| 270 | +```csharp |
| 271 | +[FunctionName(nameof(PostSample))] |
| 272 | +[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.OK)] |
| 273 | +... |
| 274 | +public static async Task<IActionResult> PostSample( |
| 275 | + [HttpTrigger(AuthorizationLevel.Function, "post", Route = "samples")] HttpRequest req, |
| 276 | + ILogger log) |
| 277 | +{ |
| 278 | + ... |
| 279 | +} |
| 280 | +``` |
| 281 | + |
| 282 | +* `StatusCode`: defines the HTTP status code. eg) `HttpStatusCode.OK` |
| 283 | +* `Summary`: is the summary of the response. |
| 284 | +* `Description`: is the description of the response. |
| 285 | + |
| 286 | + |
| 287 | +## Supported Json.NET Decorators ## |
| 288 | + |
| 289 | +Those attribute classes from [Json.NET](https://www.newtonsoft.com/json) are supported for payload definitions. |
| 290 | + |
| 291 | + |
| 292 | +### `JsonIgnore` ### |
| 293 | + |
| 294 | +Properties decorated with the `JsonIgnore` attribute class will not be included in the response. |
| 295 | + |
| 296 | + |
| 297 | +### `JsonProperty` ### |
| 298 | + |
| 299 | +Properties decorated with `JsonProperty` attribute class will use `JsonProperty.Name` value instead of their property names. In addition to this, if `JsonProperty.Required` property has `Required.Always` or `Required.DisallowNull`, the property will be recognised as the `required` field. |
| 300 | + |
| 301 | + |
| 302 | +### `JsonRequired` ### |
| 303 | + |
| 304 | +Properties decorated with `JsonRequired` attribute class will be recognised as the `required` field. |
| 305 | + |
| 306 | + |
| 307 | +### `JsonConverter` ### |
| 308 | + |
| 309 | +Enums types decorated with `[JsonConverter(typeof(StringEnumConverter))]` will appear in the document with their string names (names mangled based on default property naming standard). |
0 commit comments