@@ -29,138 +29,6 @@ dotnet add <PROJECT> package Aliencube.AzureFunctions.Extensions.OpenApi
2929```
3030
3131
32- ### Option 1. Install Open API Boilerplate Templates ###
33-
34- 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.
35-
36-
37- #### Download Installation Scripts ###
38-
39- Download the installation script using the PowerShell command.
40-
41- ``` powershell
42- # PowerShell
43- (Invoke-WebRequest `
44- -Uri "https://raw.githubusercontent.com/aliencube/AzureFunctions.Extensions/dev/scripts/Install-OpenApiHttpTriggerTemplates.ps1" `
45- -UseBasicParsing).Content | Out-File "<DIRECTORY>/Install-OpenApiHttpTriggerTemplates.ps1"
46- ```
47-
48- Alternatively, download the installation script using the Bash shell command. Make sure that the downloaded script MUST become executable.
49-
50- ``` bash
51- # Bash
52- curl -X GET " https://raw.githubusercontent.com/aliencube/AzureFunctions.Extensions/dev/scripts/Install-OpenApiHttpTriggerTemplates.sh" \
53- > " <DIRECTORY>/Install-OpenApiHttpTriggerTemplates.sh"
54-
55- chmod +x < DIRECTORY> /Install-OpenApiHttpTriggerTemplates.sh
56- ```
57-
58- > ** NOTE** : Bash command does not support Azure Functions V1.
59-
60-
61- #### Install Open API Boilerplate Templates ####
62-
63- Run the following script to install the Open API boilerplate templates in PowerShell.
64-
65- ``` powershell
66- # PowerShell
67- <DIRECTORY>/Install-OpenApiHttpTriggerTemplates.ps1 `
68- -ProjectPath <PROJECT> ` # Optional parameter. If omitted, it is set to the current directory.
69- -Namespace <NAMESPACE> ` # Optional parameter. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi
70- -IsVersion1 # Optional switch only for Azure Functions v1.
71- ```
72-
73- Alternatively, run the following script to install the Open API boilerplate templates in Bash shell.
74-
75- ``` bash
76- # Bash script
77- < DIRECTORY> /Install-OpenApiHttpTriggerTemplates.sh \
78- < PROJECT> \ # Optional argument. If omitted, it is set to the current directory.
79- < NAMESPACE> # Optional argument. If omitted, it is set to Aliencube.AzureFunctions.Extensions.OpenApi
80- ```
81-
82- > ** NOTE** : Bash script does not support Azure Functions V1.
83-
84-
85- ### Option 2. Write Open API Boilerplate Codes Manually ###
86-
87- Instead of installing the boilerplate code above, you can write the Open API boilerplate codes all by yourself.
88-
89-
90- #### Open API Document Endpoint - ` swagger.json ` ####
91-
92- In order to render the ` swagger.json ` document, define the HTTP endpoint for it.
93-
94- ``` csharp
95- [FunctionName (nameof (RenderSwaggerDocument ))]
96- [OpenApiIgnore ]
97- public static async Task < IActionResult > RenderSwaggerDocument (
98- [HttpTrigger (AuthorizationLevel .Function , " get" , Route = " swagger.json" )] HttpRequest req ,
99- ILogger log )
100- {
101- var openApiInfo = OpenApiInfoResolver .Resolve ();
102- var host = HostJsonResolver .Resolve ();
103- var httpSettings = host .GetHttpSettings ();
104-
105- var filter = new RouteConstraintFilter ();
106- var helper = new DocumentHelper (filter );
107- var document = new Document (helper );
108- var result = await document .InitialiseDocument ()
109- .AddMetadata (openApiInfo )
110- .AddServer (req , httpSettings .RoutePrefix )
111- .Build (Assembly .GetExecutingAssembly (), new CamelCaseNamingStrategy ())
112- // Depending on what you pass, the rendered document can comply Open API v2 or v3, or JSON or YAML.
113- .RenderAsync (OpenApiSpecVersion .OpenApi2_0 , OpenApiFormat .Json )
114- .ConfigureAwait (false );
115-
116- var response = new ContentResult ()
117- {
118- Content = result ,
119- ContentType = " application/json" ,
120- StatusCode = (int )HttpStatusCode .OK
121- };
122-
123- return response ;
124- }
125- ```
126-
127- > ** 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.
128-
129-
130- #### Swagger UI Page Endpoint ####
131-
132- In order to render the Swagger UI page, define the HTTP endpoint for it.
133-
134- ``` csharp
135- [FunctionName (nameof (RenderSwaggerUI ))]
136- [OpenApiIgnore ]
137- public static async Task < IActionResult > RenderSwaggerUI (
138- [HttpTrigger (AuthorizationLevel .Function , " get" , Route = " swagger/ui" )] HttpRequest req ,
139- ILogger log )
140- {
141- var openApiInfo = OpenApiInfoResolver .Resolve ();
142- var host = HostJsonResolver .Resolve ();
143- var httpSettings = host .GetHttpSettings ();
144- var swaggerAuthKey = Environment .GetEnvironmentVariable (" OpenApi__ApiKey" );
145-
146- var ui = new SwaggerUI ();
147- var result = await ui .AddMetadata (openApiInfo )
148- .AddServer (req , httpSettings .RoutePrefix )
149- .BuildAsync ()
150- .RenderAsync (" swagger.json" , swaggerAuthKey )
151- .ConfigureAwait (false );
152- var response = new ContentResult ()
153- {
154- Content = result ,
155- ContentType = " text/html" ,
156- StatusCode = (int )HttpStatusCode .OK
157- };
158-
159- return response ;
160- }
161- ```
162-
163-
16432### Expose Endpoints to Open API Document ###
16533
16634In order to include HTTP endpoints into the Open API document, use attribute classes (decorators) like:
0 commit comments