Update README.md

justinyoo · justinyoo · commit 0c0e7c004fbe · 2020-07-15T12:26:44.000+09:00
diff --git a/docs/openapi-cli.md b/docs/openapi-cli.md
@@ -12,6 +12,11 @@ This generates Open API document through command-line without having to run the
 * 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).
 
 
+## Issues? ##
+
+While using this CLI, if you find any issue, please raise a ticket on the [Issue](https://github.com/aliencube/AzureFunctions.Extensions/issues) page.
+
+
 ## Getting Started ##
 
 ### Download CLI ###
@@ -60,12 +65,12 @@ For Linux/MacOS
 
 Here are options:
 
-* `--project|-p`: Project path. It can be a fully qualified project path including `.csproj` or project directory. Default is the current directory.
-* `--configuration|-c`: Configuration value. It can be either `Debug`, `Release` or something else. Default is `Debug`.
-* `--target|-t`: Target framework. It should be `net4x` for Azure Functions v1, `netcoreapp2.x` for Azure Functions v2, and `netcoreapp3.x` for Azure Functions v3. Default is `netcoreapp2.1`.
-* `--version|-v`: Open API spec version. It should be either `v2` or `v3`. Default is `v2`.
-* `--format|-f`: Open API document format. It should be either `json` or `yaml`. Default is `json`.
-* `--output|-o`: Output directory for the generated Open API document. It can be a fully qualified directory path or relative path from `<PROJECT_ROOT>/bin/<CONFIGURATION>/<TARGET_FRAMEWORK>`. Default is `output`.
+* `-p|--project`: Project path. It can be a fully qualified project path including `.csproj` or project directory. Default is the current directory.
+* `-c|--configuration`: Configuration value. It can be either `Debug`, `Release` or something else. Default is `Debug`.
+* `-t|--target`: Target framework. It should be `net4x` for Azure Functions v1, `netcoreapp2.x` for Azure Functions v2, and `netcoreapp3.x` for Azure Functions v3. Default is `netcoreapp2.1`.
+* `-v|--version`: Open API spec version. It should be either `v2` or `v3`. Default is `v2`.
+* `-f|--format`: Open API document format. It should be either `json` or `yaml`. Default is `json`.
+* `-o|--output`: Output directory for the generated Open API document. It can be a fully qualified directory path or relative path from `<PROJECT_ROOT>/bin/<CONFIGURATION>/<TARGET_FRAMEWORK>`. Default is `output`.
 * `--console`: Value indicating whether to display the generated document to console or not. Default is `false`.
 
 
diff --git a/docs/openapi.md b/docs/openapi.md
@@ -13,76 +13,83 @@ This enables Azure Functions to render Open API document and Swagger UI. The mor
 * [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).
 
 
+## Issues? ##
+
+While using this library, if you find any issue, please raise a ticket on the [Issue](https://github.com/aliencube/AzureFunctions.Extensions/issues) page.
+
+
 ## Getting Started ##
 
-### Install Open API Templates ###
+### Install NuGet Package ###
+
+In order for your Azure Functions app to enable Open API capability, download the following NuGet package into your Azure Functions project.
+
+```bash
+dotnet add <PROJECT> 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 ###
 
-First of all, download the installation script from GitHub.
+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 "scripts/Install-OpenApiHttpTriggerTemplates.ps1"
+    -UseBasicParsing).Content | Out-File "<DIRECTORY>/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" > "scripts/Install-OpenApiHttpTriggerTemplates.sh"
+curl -X GET "https://raw.githubusercontent.com/aliencube/AzureFunctions.Extensions/dev/scripts/Install-OpenApiHttpTriggerTemplates.sh" \
+    > "<DIRECTORY>/Install-OpenApiHttpTriggerTemplates.sh"
+
+chmod +x <DIRECTORY>/Install-OpenApiHttpTriggerTemplates.sh
 ```
 
-For bash script, run the following command to enable an appropriate permission.
+> **NOTE**: Bash command does not support Azure Functions V1.
 
-```bash
-# Bash
-chmod +x scripts/Download-OpenApiHttpTriggerTemplates.sh
-```
 
-#### Install Open API Templates ####
+#### Install Open API Boilerplate Templates ####
 
-Run the following script to install the Open API templates.
+Run the following script to install the Open API boilerplate templates in PowerShell.
 
 ```powershell
 # PowerShell
-scripts/Install-OpenApiHttpTriggerTemplates.ps1 `
-    -ProjectPath ./samples/Aliencube.AzureFunctions.FunctionAppV3Static `
-    -Namespace Aliencube.AzureFunctions.FunctionAppV3Static
+<DIRECTORY>/Install-OpenApiHttpTriggerTemplates.ps1 `
+    -ProjectPath <PROJECT> ` # Optional parameter. If omitted, it is set to the current directory.
+    -Namespace <NAMESPACE> ` # Optional parameter. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi
+    -IsVersion1              # Optional switch only for Azure Functions v1.
 ```
 
-> **NOTE**: If you're running v1, add a switch, `-IsVersion1` at the end of the PowerShell script.
+Alternatively, run the following script to install the Open API boilerplate templates in Bash shell.
 
 ```bash
 # Bash script
-scripts/Install-OpenApiHttpTriggerTemplates.sh \
-    ./samples/Aliencube.AzureFunctions.FunctionAppV3Static \
-    Aliencube.AzureFunctions.FunctionAppV3Static
+<DIRECTORY>/Install-OpenApiHttpTriggerTemplates.sh \
+    <PROJECT> \ # Optional argument. If omitted, it is set to the current directory.
+    <NAMESPACE> # Optional argument. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi
 ```
 
-However, if you want to manually integrate by yourself, follow the next steps.
+> **NOTE**: Bash script does not support Azure Functions V1.
 
 
-### Rendering Open API Document ###
+### Option 2. Write Open API Boilerplate Codes Manually ###
 
-In order to include an HTTP endpoint in the Open API document, use attribute classes (decorators) like:
+Instead of installing the boilerplate code above, you can write the Open API boilerplate codes all by yourself.
 
-```csharp
-[FunctionName(nameof(PostSample))]
-[OpenApiOperation("add", "sample")]
-[OpenApiRequestBody("application/json", typeof(SampleRequestModel))]
-[OpenApiResponseBody(HttpStatusCode.OK, "application/json", typeof(SampleResponseModel))]
-public static async Task<IActionResult> PostSample(
-    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "samples")] HttpRequest req,
-    ILogger log)
-{
-    ...
-}
-```
 
-Then, define another HTTP endpoint to render Swagger document:
+#### Open API Document Endpoint - `swagger.json` ####
+
+In order to render the `swagger.json` document, define the HTTP endpoint for it.
 
 ```csharp
 [FunctionName(nameof(RenderSwaggerDocument))]
@@ -102,8 +109,10 @@ public static async Task<IActionResult> RenderSwaggerDocument(
                                .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,
@@ -118,9 +127,9 @@ public static async Task<IActionResult> RenderSwaggerDocument(
 > **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.
 
 
-### Rendering Swagger UI ###
+#### Swagger UI Page Endpoint ####
 
-In order to render Swagger UI, define another HTTP endpoint for it:
+In order to render the Swagger UI page, define the HTTP endpoint for it.
 
 ```csharp
 [FunctionName(nameof(RenderSwaggerUI))]
@@ -132,7 +141,7 @@ public static async Task<IActionResult> RenderSwaggerUI(
     var openApiInfo = OpenApiInfoResolver.Resolve();
     var host = HostJsonResolver.Resolve();
     var httpSettings = host.GetHttpSettings();
-    var swaggerAuthKey = ConfigurationResolver.GetValue<string>("OpenApi:ApiKey");
+    var swaggerAuthKey = Environment.GetEnvironmentVariable("OpenApi__ApiKey");
 
     var ui = new SwaggerUI();
     var result = await ui.AddMetadata(openApiInfo)
@@ -152,15 +161,47 @@ public static async Task<IActionResult> RenderSwaggerUI(
 ```
 
 
-## Open API Metadata ##
+### Expose Endpoints to Open API Document ###
 
-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 three places &ndash; `host.json`, `openapisettings.json` or `local.settings.json`.
+In order to include HTTP endpoints into the Open API document, use attribute classes (decorators) like:
+
+```csharp
+[FunctionName(nameof(PostSample))]
+[OpenApiOperation("postSample", "sample")]
+[OpenApiRequestBody("application/json", typeof(SampleRequestModel))]
+[OpenApiResponseBody(HttpStatusCode.OK, "application/json", typeof(SampleResponseModel))]
+public static async Task<IActionResult> PostSample(
+    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "samples")] HttpRequest req,
+    ILogger log)
+{
+    ...
+}
+```
+
+
+### Configure App Settings Key ###
+
+This key is only required if:
+
+* The Function app is deployed to Azure, and
+* The Open API related endpoints has the `AuthorizationLevel` value other than `Anonymous`.
+
+If the above conditions are met, add the following key to your `locall.settings.json` or App Settings blade on Azure.
+
+* `OpenApi__ApiKey`: either the host key value or the master key value.
+
+> **NOTE**: It is NOT required if your Open API related endpoints are set to the authorisation level of `Anonymous`.
+
+
+## Open API Metadata Configuration ##
+
+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 &ndash; `host.json`, `openapisettings.json` or `local.settings.json`.
 
 This library looks for the information in the following order:
 
 1. `host.json`
 2. `openapisettings.json`
-3. `local.settings.json` or App Settings blade
+3. `local.settings.json` or App Settings blade on Azure
 
 
 ### `host.json` ###
@@ -172,7 +213,7 @@ Although it has not been officially accepted to be a part of `host.json`, the Op
   ...
   "openApi": {
     "info": {
-      "version": "3.0.0",
+      "version": "1.0.0",
       "title": "Open API Sample on Azure Functions",
       "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from **host. json**.",
       "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions",
@@ -199,7 +240,7 @@ The Open API metadata can be defined in a separate file, `openapisettings.json`
 ```json
 {
   "info": {
-    "version": "3.0.0",
+    "version": "1.0.0",
     "title": "Open API Sample on Azure Functions",
     "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from  **openapisettings.json**.",
     "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions",
@@ -216,9 +257,10 @@ The Open API metadata can be defined in a separate file, `openapisettings.json`
 }
 ```
 
-### `local.settings.json` or App Settings ###
 
-On either your `local.settings.json` or App Settings on Azure Functions instance, those details should be set up to render Open API metadata:
+### `local.settings.json` or App Settings Blade ###
+
+On either your `local.settings.json` or App Settings on Azure Functions instance, those details can be set up like:
 
 * `OpenApi__Info__Version`: **REQUIRED** Version of Open API document. This is not the version of Open API spec. eg. 1.0.0
 * `OpenApi__Info__Title`: **REQUIRED** Title of Open API document. eg. Open API Sample on Azure Functions
@@ -229,9 +271,8 @@ On either your `local.settings.json` or App Settings on Azure Functions instance
 * `OpenApi__Info__Contact__Url`: Contact URL. eg. https://github.com/aliencube/AzureFunctions.Extensions/issues
 * `OpenApi__Info__License__Name`: **REQUIRED** License name. eg. MIT
 * `OpenApi__Info__License__Url`: License URL. eg. http://opensource.org/licenses/MIT
-* `OpenApi__ApiKey`: API Key of the endpoint that renders the Open API document.
 
-> **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/bs-latn-ba/azure/azure-functions/functions-app-settings#azurewebjobsscriptroot).
+> **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).
 
 
 ## Decorators ##
diff --git a/scripts/Install-OpenApiHttpTriggerTemplates.ps1 b/scripts/Install-OpenApiHttpTriggerTemplates.ps1
@@ -1,6 +1,6 @@
 Param(
-    [string] [Parameter(Mandatory=$true)] $ProjectPath,
-    [string] [Parameter(Mandatory=$true)] $Namespace,
+    [string] [Parameter(Mandatory=$false)] $ProjectPath = ".",
+    [string] [Parameter(Mandatory=$false)] $Namespace = "Aliencube.AzureFunctions.Extensions.OpenApi",
     [switch] [Parameter(Mandatory=$false)] $IsVersion1
 )
 
diff --git a/scripts/Install-OpenApiHttpTriggerTemplates.sh b/scripts/Install-OpenApiHttpTriggerTemplates.sh
@@ -3,6 +3,9 @@
 path=$1
 namespace=$2
 
+[ -z "$path" ] && path=.
+[ -z "$namespace" ] && namespace=Aliencube.AzureFunctions.Extensions.OpenApi
+
 # Checks if directory exists
 [ ! -d "$path/OpenApi" ] && mkdir -p "$path/OpenApi"
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`Param(`
`2`		`- [string] [Parameter(Mandatory=$true)] $ProjectPath,`
`3`		`- [string] [Parameter(Mandatory=$true)] $Namespace,`
	`2`	`+ [string] [Parameter(Mandatory=$false)] $ProjectPath = ".",`
	`3`	`+ [string] [Parameter(Mandatory=$false)] $Namespace = "Aliencube.AzureFunctions.Extensions.OpenApi",`
`4`	`4`	`[switch] [Parameter(Mandatory=$false)] $IsVersion1`
`5`	`5`	`)`
`6`	`6`