diff --git a/docs/openapi.md b/docs/openapi.md index f9fbe5a..f63e327 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -29,138 +29,6 @@ dotnet add package Aliencube.AzureFunctions.Extensions.OpenApi ``` -### Option 1. Install Open API Boilerplate Templates ### - -This is the easiest way to integrate the Open API document rendering. Run the following script based on your preference, which will install the pre-defined Open API document rendering endpoints. - - -#### Download Installation Scripts ### - -Download the installation script using the PowerShell command. - -```powershell -# PowerShell -(Invoke-WebRequest ` - -Uri "https://raw.githubusercontent.com/aliencube/AzureFunctions.Extensions/dev/scripts/Install-OpenApiHttpTriggerTemplates.ps1" ` - -UseBasicParsing).Content | Out-File "/Install-OpenApiHttpTriggerTemplates.ps1" -``` - -Alternatively, download the installation script using the Bash shell command. Make sure that the downloaded script MUST become executable. - -```bash -# Bash -curl -X GET "https://raw.githubusercontent.com/aliencube/AzureFunctions.Extensions/dev/scripts/Install-OpenApiHttpTriggerTemplates.sh" \ - > "/Install-OpenApiHttpTriggerTemplates.sh" - -chmod +x /Install-OpenApiHttpTriggerTemplates.sh -``` - -> **NOTE**: Bash command does not support Azure Functions V1. - - -#### Install Open API Boilerplate Templates #### - -Run the following script to install the Open API boilerplate templates in PowerShell. - -```powershell -# PowerShell -/Install-OpenApiHttpTriggerTemplates.ps1 ` - -ProjectPath ` # Optional parameter. If omitted, it is set to the current directory. - -Namespace ` # Optional parameter. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi - -IsVersion1 # Optional switch only for Azure Functions v1. -``` - -Alternatively, run the following script to install the Open API boilerplate templates in Bash shell. - -```bash -# Bash script -/Install-OpenApiHttpTriggerTemplates.sh \ - \ # Optional argument. If omitted, it is set to the current directory. - # Optional argument. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi -``` - -> **NOTE**: Bash script does not support Azure Functions V1. - - -### Option 2. Write Open API Boilerplate Codes Manually ### - -Instead of installing the boilerplate code above, you can write the Open API boilerplate codes all by yourself. - - -#### Open API Document Endpoint - `swagger.json` #### - -In order to render the `swagger.json` document, define the HTTP endpoint for it. - -```csharp -[FunctionName(nameof(RenderSwaggerDocument))] -[OpenApiIgnore] -public static async Task RenderSwaggerDocument( - [HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger.json")] HttpRequest req, - ILogger log) -{ - var openApiInfo = OpenApiInfoResolver.Resolve(); - var host = HostJsonResolver.Resolve(); - var httpSettings = host.GetHttpSettings(); - - var filter = new RouteConstraintFilter(); - var helper = new DocumentHelper(filter); - var document = new Document(helper); - var result = await document.InitialiseDocument() - .AddMetadata(openApiInfo) - .AddServer(req, httpSettings.RoutePrefix) - .Build(Assembly.GetExecutingAssembly(), new CamelCaseNamingStrategy()) - // Depending on what you pass, the rendered document can comply Open API v2 or v3, or JSON or YAML. - .RenderAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json) - .ConfigureAwait(false); - - var response = new ContentResult() - { - Content = result, - ContentType = "application/json", - StatusCode = (int)HttpStatusCode.OK - }; - - return response; -} -``` - -> **NOTE**: In order to render payload definitions in `camelCasing`, add `new CamelCaseNamingStrategy()` as an optional argument to the `Build()` method. If this is omitted, payload will be rendered as defined in the payload definitions. - - -#### Swagger UI Page Endpoint #### - -In order to render the Swagger UI page, define the HTTP endpoint for it. - -```csharp -[FunctionName(nameof(RenderSwaggerUI))] -[OpenApiIgnore] -public static async Task RenderSwaggerUI( - [HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger/ui")] HttpRequest req, - ILogger log) -{ - var openApiInfo = OpenApiInfoResolver.Resolve(); - var host = HostJsonResolver.Resolve(); - var httpSettings = host.GetHttpSettings(); - var swaggerAuthKey = Environment.GetEnvironmentVariable("OpenApi__ApiKey"); - - var ui = new SwaggerUI(); - var result = await ui.AddMetadata(openApiInfo) - .AddServer(req, httpSettings.RoutePrefix) - .BuildAsync() - .RenderAsync("swagger.json", swaggerAuthKey) - .ConfigureAwait(false); - var response = new ContentResult() - { - Content = result, - ContentType = "text/html", - StatusCode = (int)HttpStatusCode.OK - }; - - return response; -} -``` - - ### Expose Endpoints to Open API Document ### In order to include HTTP endpoints into the Open API document, use attribute classes (decorators) like: