Merge branch 'v2' into release/v2.0.0-preview1

Azure · Dec 23, 2022 · a315816 · a315816
2 parents 9d1c5ca + 0680435
commit a315816
Show file tree

Hide file tree

Showing 9 changed files with 106 additions and 148 deletions.
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@
 ## Acknowledgement ##
 
 * [Swagger UI](https://github.com/swagger-api/swagger-ui) version used for this library is [v3.44.0](https://github.com/swagger-api/swagger-ui/releases/tag/v3.44.0) under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0).
+* This extension supports the OpenAPI spec version of [v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) and [v3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md).
 
 
 ## Getting Started ##
@@ -17,74 +18,25 @@
   * [**Microsoft.Azure.WebJobs.Extensions.OpenApi**](docs/openapi-in-proc.md)
   * [**Microsoft.Azure.WebJobs.Extensions.OpenApi.Core**](docs/openapi-core.md)
 * [**Securing Azure Functions Endpoints through OpenAPI Auth**](docs/openapi-auth.md): This document shows many various scenarios to add authN features including the built-in features and OAuth2 auth flows.
-* [**Azure Functions v1 Support**](docs/azure-functions-v1-support.md): This document shows how to support Azure Functions v1 runtime with this OpenAPI extension.
+* ~~[**Azure Functions v1 Support**](docs/azure-functions-v1-support.md): This document shows how to support Azure Functions v1 runtime with this OpenAPI extension.~~
 * [**Integrating OpenAPI-enabled Azure Functions to Azure API Management**](docs/integrate-with-apim.md): This document shows how to integrate the Azure Functions application with [Azure API Management](https://docs.microsoft.com/azure/api-management/api-management-key-concepts?WT.mc_id=dotnet_0000_juyoo), via this OpenAPI extension.
 <!-- * [**Integrating OpenAPI-enabled Azure Functions to Power Platform**](docs/integrate-with-powerplatform.md): This document shows how to integrate the Azure Functions application with [Power Platform](https://powerplatform.microsoft.com/?WT.mc_id=dotnet_0000_juyoo), via this OpenAPI extension. -->
+* [**Generic CI/CD Pipeline Support](./docs/generic-cicd-pipeline-support.md): This document shows how to generate the OpenAPI document within a CI/CD pipeline, using either PowerShell or bash shell script.
 
 
 ## GitHub Actions Support ##
 
 If you are using GitHub Actions as your preferred CI/CD pipeline, you can run the GitHub Action into your workflow to automatically generate the OpenAPI document. Find more details at the [Build OpenAPI](./actions/build-openapi/) action page.
 
 
-## Generic CI/CD Pipeline Support ##
+## GitHub Codespaces Support ##
 
-Alternatively, you can run either PowerShell script or bash shell script to generate the OpenAPI document within your own CI/CD pipeline other than GitHub Actions. Here are two script files:
+If you want to run your Azure Functions app on GitHub Codespaces, you might want to accommodate `local.settings.json`. The following PowerShell script may help you for the accommodation:
 
-* PowerShell: [Get-OpenApiDocument.ps1](./actions/Get-OpenApiDocument.ps1)
-
-    ```powershell
-    ./actions/Get-OpenApiDocument.ps1 `
-        -FunctionAppPath    <function app directory> `
-        -BaseUri            <function app base URI> `
-        -Endpoint           <endpoint for OpenAPI document> `
-        -OutputPath         <output directory for generated OpenAPI document> `
-        -OutputFilename     <OpenAPI document name> `
-        -Delay              <delay in second between run function app and document generation> `
-        -UseWindows         <switch indicating whether to use Windows OS or not>
-    ```
-
-    For more details, run `Get-OpenApiDocument.ps1 -Help`
-
-    You can also remotely invoke this PowerShell script:
-
-    ```powershell
-    & $([Scriptblock]::Create($(Invoke-RestMethod https://aka.ms/azfunc-openapi/generate-openapi.ps1))) `
-        -FunctionAppPath    <function app directory> `
-        -BaseUri            <function app base URI> `
-        -Endpoint           <endpoint for OpenAPI document> `
-        -OutputPath         <output directory for generated OpenAPI document> `
-        -OutputFilename     <OpenAPI document name> `
-        -Delay              <delay in second between run function app and document generation> `
-        -UseWindows         <switch indicating whether to use Windows OS or not>
-    ```
-
-* Bash shell: [get-openapi-document.sh](./actions/get-openapi-document.sh)
-
-    ```bash
-    ./actions/get-openapi-document.sh \
-        -p|--functionapp-path   <function app directory> \
-        -u|--base-uri           <function app base URI> \
-        -e|--endpoint           <endpoint for OpenAPI document> \
-        -o|--output-path        <output directory for generated OpenAPI document> \
-        -f|--output-filename    <OpenAPI document name> \
-        -d|--delay              <delay in second between run function app and document generation>
-    ```
-
-    For more details, run `get-openapi-document.sh --help`
-
-    You can also remotely invoke this bash shell script:
-
-    ```bash
-    curl -fsSL https://aka.ms/azfunc-openapi/generate-openapi.sh \
-        | bash -s -- \
-            -p|--functionapp-path   <function app directory> \
-            -u|--base-uri           <function app base URI> \
-            -e|--endpoint           <endpoint for OpenAPI document> \
-            -o|--output-path        <output directory for generated OpenAPI document> \
-            -f|--output-filename    <OpenAPI document name> \
-            -d|--delay              <delay in second between run function app and document generation>
-    ```
+```bash
+# Update local.settings.json
+pwsh -c "Invoke-RestMethod https://aka.ms/azfunc-openapi/add-codespaces.ps1 | Invoke-Expression"
+```
 
 
 ## Sample Azure Function Apps with OpenAPI Document Enabled ##
@@ -95,9 +47,9 @@ Here are sample apps using the project references:
 * [Function App in-proc worker](samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.InProc)
 
 
-## Azure Functions V1 Support ##
+~~## Azure Functions V1 Support ##~~
 
-This library supports Azure Functions V3 and onwards. If you still want to get your v1 and v2 runtime app supported, find the [community contribution](https://github.com/aliencube/AzureFunctions.Extensions) or the [proxy feature](docs/azure-functions-v1-support.md).
+~~This library supports Azure Functions V3 and onwards. If you still want to get your v1 and v2 runtime app supported, find the [community contribution](https://github.com/aliencube/AzureFunctions.Extensions) or the [proxy feature](docs/azure-functions-v1-support.md).~~
 
 
 ## Known Issues ##

diff --git a/docs/README.md b/docs/README.md
@@ -11,4 +11,3 @@ This extension adds the OpenAPI capability to your Azure Functions app.
 | [Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings](app-settings.md) | [![](https://img.shields.io/nuget/dt/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings/) | [![](https://img.shields.io/nuget/v/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings/) |
 | [Microsoft.Azure.WebJobs.Extensions.OpenApi.Core](openapi-core.md) | [![](https://img.shields.io/nuget/dt/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/) | [![](https://img.shields.io/nuget/v/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/) |
 | [Microsoft.Azure.WebJobs.Extensions.OpenApi](openapi-in-proc.md) | [![](https://img.shields.io/nuget/dt/Microsoft.Azure.WebJobs.Extensions.OpenApi.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi/) | [![](https://img.shields.io/nuget/v/Microsoft.Azure.WebJobs.Extensions.OpenApi.svg)](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi/) |
-| [Microsoft.Azure.WebJobs.Extensions.OpenApi.CLI](openapi-cli.md) | [![](https://img.shields.io/static/v1?label=tag&message=cli-*&color=brightgreen)](https://github.com/Azure/azure-functions-openapi-extension/releases) | [![](https://img.shields.io/static/v1?label=tag&message=cli-*&color=brightgreen)](https://github.com/Azure/azure-functions-openapi-extension/releases) |
diff --git a/docs/enable-open-api-endpoints-in-proc.md b/docs/enable-open-api-endpoints-in-proc.md
@@ -3,7 +3,7 @@
 [OpenAPI metadata][openapi] supports in Azure Functions is now available with this extension, [Azure Functions OpenAPI Extension (In-Process Worker)][az func openapi extension]. With this extension, you can directly let your API endpoints be discoverable.
 
 > [!IMPORTANT]
-> This extension supports only Azure Functions v2 and onwards. If you want to get your Azure Functions v1 supported, find [this preview document][az func openapi v1 preview] or [community contribution][az func openapi community]. You may also want to see [this out-of-process model][docs out-of-proc].
+> This extension supports only up to .NET 6. If you want to use .NET Framework 4.8.x and .NET 7+, find [this out-of-process model][docs out-of-proc].
 
 [OpenAPI metadata][openapi] allows wide variety of other software and applications to consume an Azure Functions app hosting HTTP APIs. The software and applications include Microsoft products and services like [Power Platform][power platform], [API Management][az apim] and third-party tools like [Postman][postman].
 
@@ -13,9 +13,9 @@
 To get yourself started, you need to have the followings installed on your local machine.
 
 > [!IMPORTANT]
-> This extension is currently available in .NET Core runtime.
+> This extension is currently available in .NET 6 runtime.
 
-* [.NET Core SDK 3.1 LTS][dotnet core sdk]
+* [.NET 6 SDK LTS][dotnet sdk]
 * [Azure Functions Core Tools][az func core tools]
 * [Visual Studio Code][vs code]
 * [Visual Studio Extensions for Azure Tools][vs code azure tools]
@@ -223,7 +223,7 @@ You have got an Azure Functions app with OpenAPI metadata enabled. In the next a
 [docs apim]: integrate-with-apim.md
 [docs powerplatform]: integrate-with-powerplatform.md
 
-[dotnet core sdk]: https://dotnet.microsoft.com/download/dotnet-core/3.1?WT.mc_id=dotnet-0000-juyoo
+[dotnet sdk]: https://dotnet.microsoft.com/download/dotnet-core/6.0?WT.mc_id=dotnet-0000-juyoo
 
 [az account free]: https://azure.microsoft.com/free/?WT.mc_id=dotnet-0000-juyoo
 [az account free students]: https://azure.microsoft.com/free/students/?WT.mc_id=dotnet-0000-juyoo

diff --git a/docs/enable-open-api-endpoints-out-of-proc.md b/docs/enable-open-api-endpoints-out-of-proc.md
@@ -3,7 +3,7 @@
 [OpenAPI metadata][openapi] supports in Azure Functions is now available with this extension, [Azure Functions OpenAPI Extension (Out-of-Process Worker)][az func openapi extension]. With this extension, you can directly let your API endpoints be discoverable.
 
 > [!IMPORTANT]
-> This extension supports only Azure Functions v3 and onwards. If you want to get your Azure Functions v2 supported, find [this in-process model][docs in-proc]. If you want to get your Azure Functions v1 supported, find [this preview document][az func openapi v1 preview] or [community contribution][az func openapi community].
+> This extension supports both .NET Framework 4.8.x and .NET 7+. If you want to use .NET 6, find [this in-process model][docs in-proc].
 
 [OpenAPI metadata][openapi] allows wide variety of other software and applications to consume an Azure Functions app hosting HTTP APIs. The software and applications include Microsoft products and services like [Power Platform][power platform], [API Management][az apim] and third-party tools like [Postman][postman].
 
@@ -13,10 +13,9 @@
 To get yourself started, you need to have the followings installed on your local machine.
 
 > [!IMPORTANT]
-> This extension is currently available in .NET Core runtime.
+> This extension is currently available in both .NET Framework 4.8.x and .NET 7+ runtime.
 
-* [.NET Core SDK 3.1 LTS][dotnet core sdk]
-* [.NET 5 SDK][dotnet 5 sdk]
+* [.NET 7 SDK STS][dotnet sdk] or [.NET 4.8 SDK][dotnet 48 sdk]
 * [Azure Functions Core Tools][az func core tools]
 * [Visual Studio Code][vs code]
 * [Visual Studio Extensions for Azure Tools][vs code azure tools]
@@ -105,7 +104,6 @@ namespace MyOpenApiFunctionApp
 
             // Add these lines below
                 .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
-                .ConfigureOpenApi()
             // Add these lines above
                 .Build();
 
@@ -251,8 +249,8 @@ You have got an Azure Functions app with OpenAPI metadata enabled. In the next a
 [docs apim]: integrate-with-apim.md
 [docs powerplatform]: integrate-with-powerplatform.md
 
-[dotnet core sdk]: https://dotnet.microsoft.com/download/dotnet-core/3.1?WT.mc_id=dotnet-0000-juyoo
-[dotnet 5 sdk]: https://dotnet.microsoft.com/download/dotnet/5.0?WT.mc_id=dotnet-0000-juyoo
+[dotnet sdk]: https://dotnet.microsoft.com/download/dotnet/7.0?WT.mc_id=dotnet-0000-juyoo
+[dotnet 48 sdk]: https://dotnet.microsoft.com/download/dotnet-framework/net48?WT.mc_id=dotnet-0000-juyoo
 
 [az account free]: https://azure.microsoft.com/free/?WT.mc_id=dotnet-0000-juyoo
 [az account free students]: https://azure.microsoft.com/free/students/?WT.mc_id=dotnet-0000-juyoo

diff --git a/docs/generic-cicd-pipeline-support.md b/docs/generic-cicd-pipeline-support.md
@@ -0,0 +1,64 @@
+# Generic CI/CD Pipeline Support #
+
+You can run either PowerShell script or bash shell script to generate the OpenAPI document within your own CI/CD pipeline including Azure DevOps or GitHub Actions.
+
+
+## PowerShell ##
+
+Run the PowerShell script remotely:
+
+```powershell
+& $([Scriptblock]::Create($(Invoke-RestMethod https://aka.ms/azfunc-openapi/generate-openapi.ps1))) `
+    -FunctionAppPath    <function app directory> `
+    -BaseUri            <function app base URI> `
+    -Endpoint           <endpoint for OpenAPI document> `
+    -OutputPath         <output directory for generated OpenAPI document> `
+    -OutputFilename     <OpenAPI document name> `
+    -Delay              <delay in second between run function app and document generation> `
+    -UseWindows         <switch indicating whether to use Windows OS or not>
+```
+
+Alternatively, you can manually download the PowerShell script and include it to your codebase: [Get-OpenApiDocument.ps1](./actions/Get-OpenApiDocument.ps1)
+
+```powershell
+./actions/Get-OpenApiDocument.ps1 `
+    -FunctionAppPath    <function app directory> `
+    -BaseUri            <function app base URI> `
+    -Endpoint           <endpoint for OpenAPI document> `
+    -OutputPath         <output directory for generated OpenAPI document> `
+    -OutputFilename     <OpenAPI document name> `
+    -Delay              <delay in second between run function app and document generation> `
+    -UseWindows         <switch indicating whether to use Windows OS or not>
+```
+
+For more details, run `Get-OpenApiDocument.ps1 -Help`
+
+
+## Bash Shell ##
+
+Run the bash shell script remotely:
+
+```bash
+curl -fsSL https://aka.ms/azfunc-openapi/generate-openapi.sh \
+    | bash -s -- \
+        -p|--functionapp-path   <function app directory> \
+        -u|--base-uri           <function app base URI> \
+        -e|--endpoint           <endpoint for OpenAPI document> \
+        -o|--output-path        <output directory for generated OpenAPI document> \
+        -f|--output-filename    <OpenAPI document name> \
+        -d|--delay              <delay in second between run function app and document generation>
+```
+
+Alternatively, you can manually download the PowerShell script and include it to your codebase: [get-openapi-document.sh](./actions/get-openapi-document.sh)
+
+```bash
+./actions/get-openapi-document.sh \
+    -p|--functionapp-path   <function app directory> \
+    -u|--base-uri           <function app base URI> \
+    -e|--endpoint           <endpoint for OpenAPI document> \
+    -o|--output-path        <output directory for generated OpenAPI document> \
+    -f|--output-filename    <OpenAPI document name> \
+    -d|--delay              <delay in second between run function app and document generation>
+```
+
+For more details, run `get-openapi-document.sh --help`
diff --git a/docs/openapi-cli.md b/docs/openapi-cli.md