|
| 1 | +# Aliencube.AzureFunctions.Extensions.OpenApi.CLI # |
| 2 | + |
| 3 | + [](https://github.com/aliencube/AzureFunctions.Extensions/releases) [](https://github.com/aliencube/AzureFunctions.Extensions/releases) |
| 4 | + |
| 5 | +This generates Open API document through command-line without having to run the Azure Functions instance. The more details around this CLI can be found on this [blog post](https://devkimchi.com/2020/07/08/generating-open-api-doc-for-azure-functions-in-command-line/). |
| 6 | + |
| 7 | +> **NOTE**: This CLI 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 | + |
| 14 | + |
| 15 | +## Getting Started ## |
| 16 | + |
| 17 | +### Download CLI ### |
| 18 | + |
| 19 | +The CLI is available for download at [GitHub](https://github.com/aliencube/AzureFunctions.Extensions/releases). It's always tagged with `cli-<version>`. Download the latest version of CLI. |
| 20 | + |
| 21 | +* For Azure Functions v1 |
| 22 | + * Windows only: `azfuncopenapi-v<version>-net461-win-x64.zip` |
| 23 | +* For Azure Functions v2 or later |
| 24 | + * Linux: `azfuncopenapi-v<version>-netcoreapp3.1-linux-x64.zip` |
| 25 | + * MacOS: `azfuncopenapi-v<version>-netcoreapp3.1-osx-x64.zip` |
| 26 | + * Windows: `azfuncopenapi-v<version>-netcoreapp3.1-win-x64.zip` |
| 27 | + |
| 28 | + |
| 29 | +### Generating Open API Document ### |
| 30 | + |
| 31 | +Once you have an Azure Functions instance with [Azure Functions Open API extension](openapi.md) enabled, then you are ready to run this CLI. |
| 32 | + |
| 33 | +For Windows: |
| 34 | + |
| 35 | +```powershell |
| 36 | +# PowerShell Console |
| 37 | +azfuncopenapi ` |
| 38 | + --project <PROJECT_PATH> ` |
| 39 | + --configuration Debug ` |
| 40 | + --target netcoreapp2.1 ` |
| 41 | + --version v2 ` |
| 42 | + --format json ` |
| 43 | + --output output ` |
| 44 | + --console false |
| 45 | +``` |
| 46 | + |
| 47 | +For Linux/MacOS |
| 48 | + |
| 49 | +```bash |
| 50 | +# Bash |
| 51 | +./azfuncopenapi \ |
| 52 | + --project <PROJECT_PATH> \ |
| 53 | + --configuration Debug \ |
| 54 | + --target netcoreapp2.1 \ |
| 55 | + --version v2 \ |
| 56 | + --format json \ |
| 57 | + --output output \ |
| 58 | + --console false |
| 59 | +``` |
| 60 | + |
| 61 | +Here are options: |
| 62 | + |
| 63 | +* `--project|-p`: Project path. It can be a fully qualified project path including `.csproj` or project directory. Default is the current directory. |
| 64 | +* `--configuration|-c`: Configuration value. It can be either `Debug`, `Release` or something else. Default is `Debug`. |
| 65 | +* `--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`. |
| 66 | +* `--version|-v`: Open API spec version. It should be either `v2` or `v3`. Default is `v2`. |
| 67 | +* `--format|-f`: Open API document format. It should be either `json` or `yaml`. Default is `json`. |
| 68 | +* `--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`. |
| 69 | +* `--console`: Value indicating whether to display the generated document to console or not. Default is `false`. |
| 70 | + |
| 71 | + |
| 72 | +## Roadmap ## |
| 73 | + |
| 74 | +* Distribution through a npm package. |
| 75 | +* Project boilerplate generation, if an Open API doc is provided. |
| 76 | + |
0 commit comments