Update docs

Author: justinyoo

docs/openapi-core.md

@@ -88,10 +88,19 @@ public class OpenApiConfigurationOptions : IOpenApiConfigurationOptions
     };
 
     public List<OpenApiServer> Servers { get; set; } = new List<OpenApiServer>();
+
+    public OpenApiVersionType OpenApiVersion { get; set; } = OpenApiVersionType.V2;
 }
 ```
 
-It's often required for the API app to have more than one base URL, with different hostname. To have [additional server URL information](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject), add `OpenApiServer` details to the class implementing the `IOpenApiConfigurationOptions` interface like:
+
+### Overriding Base URLs ###
+
+It's often required for the API app to have more than one base URL, with different hostname. To have [additional server URL information](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject), declare the `OpenApi__HostNames` value with comma delimited base URLs. Then, it will automatically sets up your base URLs.
+
+> Find the [Configuration](openapi.md#configuration) section for the full list of the app settings keys.
+
+Alternatively, add `OpenApiServer` details to the `Servers` property like:
 
 ```csharp
 public class OpenApiConfigurationOptions : IOpenApiConfigurationOptions
@@ -103,12 +112,36 @@ public class OpenApiConfigurationOptions : IOpenApiConfigurationOptions
         new OpenApiServer() { Url = "https://contoso.com/api/" },
         new OpenApiServer() { Url = "https://fabrikam.com/api/" },
     };
+
+    ...
+}
+```
+
+> **NOTE**:
+> 
+> * If no base URL is declared, the Azure Functions app's URL will be added as a default.
+> * The OpenAPI v2 (Swagger) document only shows the the first server name on both UI and document, while the OpenAPI v3 document shows the first server name on the UI and all server names on the document.
+
+
+### Overriding OpenAPI Version ###
+
+The default version of OpenAPI document rendered is V2 (AKA Swagger). However, you can override the default rendering behaviour by implementing the `OpenApiVersion` property.
+
+```csharp
+public class OpenApiConfigurationOptions : IOpenApiConfigurationOptions
+{
+    ...
+
+    public OpenApiVersionType OpenApiVersion { get; set; } = OpenApiVersionType.V3;
+
+    ...
 }
 ```
 
-> **NOTE**: As this extension automatically generates the server URL, these extra URLs are only appended, not overwriting the one automatically generated. And, the API v2 (Swagger) document won't be impacted by these extra URLs, while the OpenAPI v3 document shows all server URLs in the document, including the automatically generated one.
 
-Instead of implementing `IOpenApiConfigurationOptions`, you can inherit `DefaultOpenApiConfigurationOptions`. As both `Info` and `Servers` properties have the modifier of `virtual`, you can freely override both or leave them as default.
+### Inheriting `DefaultOpenApiConfigurationOptions` ###
+
+Instead of implementing `IOpenApiConfigurationOptions`, you can inherit `DefaultOpenApiConfigurationOptions`. As `Info`, `Servers` and `OpenApiVersion` properties have the modifier of `virtual`, you can freely override them or leave them as default.
 
 ```csharp
 public class MyOpenApiConfigurationOptions : DefaultOpenApiConfigurationOptions
@@ -131,6 +164,14 @@ public class MyOpenApiConfigurationOptions : DefaultOpenApiConfigurationOptions
             Url = new Uri("http://opensource.org/licenses/MIT"),
         }
     };
+
+    public override List<OpenApiServer> Servers { get; set; } = new List<OpenApiServer>()
+    {
+        new OpenApiServer() { Url = "https://contoso.com/api/" },
+        new OpenApiServer() { Url = "https://fabrikam.com/api/" },
+    };
+
+    public override OpenApiVersionType OpenApiVersion { get; set; } = OpenApiVersionType.V3;
 }
 ```
 
@@ -499,6 +540,54 @@ public static class DummyHttpTrigger
 * `Description`: is the description of the response.
 
 
+### `OpenApiExampleAttribute` ###
+
+This decorator implements the example attribute defined in the [`Schema object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#schemaObject) section.
+
+```csharp
+// Example
+public class CatExample : OpenApiExample<Cat>
+{
+    public override IOpenApiExample<Cat> Build(NamingStrategy namingStrategy = null)
+    {
+        this.Examples.Add(OpenApiExampleResolver.Resolve("nabi", new Cat() { Id = 123, Name = "Nabi" }, namingStrategy));
+
+        return this;
+    }
+}
+
+// Model
+[OpenApiExample(typeof(CatExample))]
+public class Cat
+{
+    public int Id { get; set; }
+
+    public string Name { get; set; }
+}
+
+// This will result in:
+// {
+//   "components": {
+//     "schemas": {
+//       "cat": {
+//         "type": "object",
+//         "properties": {
+//           "id": {
+//             "type": "integer"
+//             "format": "int32"
+//           },
+//           "name": {
+//             "type": "string"
+//           }
+//         },
+//         "example": "{\"id\":123,\"name\":\"Nabi\"}"
+//       }
+//     }
+//   }
+// }
+```
+
+
 ### `OpenApiSchemaVisibilityAttribute` ###
 
 This decorator is a part of extended property for custom connectors of Azure Logic Apps and Power Platform.

docs/openapi.md

@@ -22,6 +22,11 @@ While using this library, if you find any issue, please raise a ticket on the [I
 For detailed getting started document, find this [Enable OpenAPI Endpoints on Azure Functions (Preview)](enable-open-api-endpoints.md) page.
 
 
+## Configuration ##
+
+For the extension's advanced configuration, it expects the following config keys.
+
+
 ### Configure Authorization Level ###
 
 As a default, all endpoints to render Swagger UI and OpenAPI documents have the authorisation level of `AuthorizationLevel.Anonymous`. However, if you want to secure those endpoints, change their authorisation level to `AuthorizationLevel.Functions` and pass the API Key through either request header or querystring parameter. This can be done through the environment variables. Here's the sample `local.settings.json` file. The other values are omitted for brevity.
@@ -52,3 +57,16 @@ You may want to only enable the Swagger UI page during the development time, and
 ```
 
 If you set the `OpenApi__HideSwaggerUI` value to `true`, the Swagger UI page won't be showing up, and you will see the 404 error. The default value is `false`.
+
+
+### Configure Custom Base URLs ###
+
+There's a chance that you want to expose the UI and OpenAPI document through [Azure API Management](https://docs.microsoft.com/azure/api-management/api-management-key-concepts?WT.mc_id=github-0000-juyoo) or load balancing services like [Azure Front Door](https://docs.microsoft.com/azure/frontdoor/front-door-overview?WT.mc_id=github-0000-juyoo). You can configure an environment variable to add them. Here's the sample `local.settings.json` file. The other values are omitted for brevity.
+
+```json
+{
+  "Values": {
+    "OpenApi__HostNames": "https://contoso.com/api/,https://fabrikam.com/api/"
+  }
+}
+```