From eb38d41d241189e9b7480f9c46fdb5b3d90feb9a Mon Sep 17 00:00:00 2001 From: Tuomas Hietanen Date: Sat, 2 Nov 2024 14:26:38 +0000 Subject: [PATCH] Update docs (#249) --- docs/Customization.md | 16 ++++++++-------- docs/OpenApiClientProvider.md | 12 ++++++------ docs/README.md | 10 +++++----- docs/SwaggerClientProvider.md | 10 +++++----- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/Customization.md b/docs/Customization.md index 239f0fc0..f4903fec 100644 --- a/docs/Customization.md +++ b/docs/Customization.md @@ -1,7 +1,7 @@ # Customizations -OpenAPI and Swagger type providers one or several provided API client (depending on the value of `IgnoreControllerPrefix`). -Each provided API client is subclass of `ProvidedApiClientBase` that allow you control and customize HTTP calls. +OpenAPI and Swagger type providers one or several provided API clients (depending on the value of `IgnoreControllerPrefix`). +Each provided API client is a subclass of `ProvidedApiClientBase` that allows you to control and customize HTTP calls. ```fsharp type ProvidedApiClientBase(httpClient: HttpClient) = @@ -11,11 +11,11 @@ type ProvidedApiClientBase(httpClient: HttpClient) = abstract member Deserialize: string * Type -> obj ``` -Snippet shows only most important parts of `ProvidedApiClientBase`, the full source code provide default implementation for `Serialize` & `Deserialize` methods that tightly coupled with [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/). +The snippet shows only the most important parts of `ProvidedApiClientBase`, the full source code provides a default implementation for `Serialize` & `Deserialize` methods that tightly coupled with [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/). **Key features:** -1. You can provide your own instance of `HttpClient` during API client construction and control HTTP request execution (If you will not provide `HttpClient`, type provider create default one for you). -2. `Serialize` and `Deserialize` methods are abstract. If you are not happy with default `JsonSerializerSettings` you can override them and configure `Newtonsoft.Json` as you like. +1. You can provide your own instance of `HttpClient` during API client construction and control HTTP request execution (If you will not provide `HttpClient`, the type provider creates the default one for you). +2. `Serialize` and `Deserialize` methods are abstract. If you are not happy with the default `JsonSerializerSettings` you can override them and configure `Newtonsoft.Json` as you like. ## Request interception @@ -55,7 +55,7 @@ let main argv = ## Authentication -Authentication is just a special case `Request interception`. Your custom `DelegatingHandler` is fully responsible for management of authentication information (attach Authentication Header, authentication cookie, invalidate it and etc.). +Authentication is just a special case of `Request interception`. Your custom `DelegatingHandler` is fully responsible for the management of authentication information (attach Authentication Header, authentication cookie, invalidate it and etc.). ```fsharp {highlight:['4-6']} type AuthHandler(messageHandler) = @@ -80,7 +80,7 @@ let client = PetStore.Client(httpClient) ## Serialization -Serialization is also quite flexible. All you need it to define your own type for API client that will be subclass of API client generated by type provider and override `Serialize` and `Deserialize` members. +Serialization is also quite flexible. All you need is to define your own type for API client that will be a subclass of API client generated by the type provider and override `Serialize` and `Deserialize` members. @@ -132,4 +132,4 @@ let main argv = |> Async.RunSynchronously 0 -``` \ No newline at end of file +``` diff --git a/docs/OpenApiClientProvider.md b/docs/OpenApiClientProvider.md index f938af12..93f612df 100644 --- a/docs/OpenApiClientProvider.md +++ b/docs/OpenApiClientProvider.md @@ -1,6 +1,6 @@ # OpenAPI Client Provider -OpenApiClientProvider is generative F# Type Provider, build on top of [Microsoft.OpenApi.Readers](https://www.nuget.org/packages/Microsoft.OpenApi.Readers/) schema parser that supports 3.0 and 2.0 schema formats. +OpenApiClientProvider is a generative F# Type Provider, built on top of [Microsoft.OpenApi.Readers](https://www.nuget.org/packages/Microsoft.OpenApi.Readers/) schema parser that supports 3.0 and 2.0 schema formats. ```fsharp open SwaggerProvider @@ -12,7 +12,7 @@ let client = PetStore.Client() ## Parameters -`OpenApiClientProvider` supports following configuration parametes +`OpenApiClientProvider` supports the following configuration parameters | Parameter | Description | |-----------|-------------| @@ -43,15 +43,15 @@ type PetStore = OpenApiClientProvider let main argv = // `UseCookies = false` is required if you use Cookie Parameters let handler = new HttpClientHandler (UseCookies = false) - // `BaseAddress` uri should ends with '/' because TP generate relative uri + // `BaseAddress` uri should end with '/' because TP generate relative uri let baseUri = Uri("https://petstore.swagger.io/v2/") use httpClient = new HttpClient(handler, true, BaseAddress=baseUri) - // You can provide your instance of `HttpClient` to provided api client + // You can provide your instance of `HttpClient` to the provided api client // or change it any time in runtime using `client.HttpClient` property let client = PetStore.Client(httpClient) task { - // Create new instance of provided type and add to store + // Create a new instance of the provided type and add to store let pet = PetStore.Pet(Id = Some(24L), Name = "Shani") do! client.AddPet(pet) @@ -62,4 +62,4 @@ let main argv = |> Async.AwaitTask |> Async.RunSynchronously 0 -``` \ No newline at end of file +``` diff --git a/docs/README.md b/docs/README.md index 8cf43062..4841f28b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,11 @@ [![NuGet Badge](https://buildstats.info/nuget/SwaggerProvider?includePreReleases=true)](https://www.nuget.org/packages/SwaggerProvider) -`SwaggerProvider` is an umbrella project for two F# generative Type Providers that generate object model and HTTP clients for APIs described by [OpenApi 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) and [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) schemas +`SwaggerProvider` is an umbrella project for two F# generative Type Providers that generate object models and HTTP clients for APIs described by [OpenApi 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) and [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) schemas - [OpenApiClientProvider](/OpenApiClientProvider) New - uses [Microsoft.OpenApi.Readers](https://www.nuget.org/packages/Microsoft.OpenApi.Readers/) to parse schema. Support both OpenApi and Swagger schemas, but Swagger support is limited. -- [SwaggerClientProvider](/SwaggerClientProvider) - uses custom old good Swagger 2.0 schema parser and tested on several hundreds schemas available in [APIs.guru](https://apis.guru/openapi-directory/) (Wikipedia for WEB APIs) +- [SwaggerClientProvider](/SwaggerClientProvider) - uses custom old good Swagger 2.0 schema parser and tested on several hundred schemas available in [APIs.guru](https://apis.guru/openapi-directory/) (Wikipedia for WEB APIs) -Type Providers support schemas in `JSON` & `YAML` formats and runs on `netcoreapp3.1` and `net46`. +Type Providers support schemas in `JSON` & `YAML` formats and run on `netcoreapp3.1` and `net46`. ### Getting started @@ -56,13 +56,13 @@ let main argv = 0 ``` -build and run project +build and run the project ```bash dotnet run ``` -in the console you should see printed inventory from the server. +in the console, you should see printed inventory from the server. ### Intellisense diff --git a/docs/SwaggerClientProvider.md b/docs/SwaggerClientProvider.md index 50dc8e5a..6a3d5e90 100644 --- a/docs/SwaggerClientProvider.md +++ b/docs/SwaggerClientProvider.md @@ -2,11 +2,11 @@ -The SwaggerClientProvider is outdated. There is no plans to improve custom Swagger 2.0 schema parser or bring new features to this type provider. We hope to remove it from source code when users migrate to [OpenApiClientProvider](/OpenApiClientProvider) and OpenApi 3.0 schemas. +The SwaggerClientProvider is outdated. There are no plans to improve the custom Swagger 2.0 schema parser or bring new features to this type provider. We hope to remove it from the source code when users migrate to [OpenApiClientProvider](/OpenApiClientProvider) and OpenApi 3.0 schemas. -SwaggerClientProvider is generative F# Type Provider, build on top of custom Swagger schema parser that supports **only** 2.0 schema format. +SwaggerClientProvider is a generative F# Type Provider, built on top of a custom Swagger schema parser that supports **only** 2.0 schema format. ```fsharp open SwaggerProvider @@ -18,12 +18,12 @@ let petStore = PetStore.Client() ## Parameters -When you use TP you can specify following parameters +When you use TP you can specify the following parameters | Parameter | Description | |-----------|-------------| | `Schema` | Url or Path to Swagger schema file. | -| `Headers` | HTTP Headers requiried to access the schema. | +| `Headers` | HTTP Headers required to access the schema. | | `IgnoreOperationId` | Do not use `operationsId` and generate method names using `path` only. Default value `false`. | | `IgnoreControllerPrefix` | Do not parse `operationsId` as `_` and generate one client class for all operations. Default value `true`. | | `PreferNullable` | Provide `Nullable<_>` for not required properties, instead of `Option<_>`. Defaults value `false`. | @@ -47,7 +47,7 @@ let main argv = // Type Provider creates HttpClient for you under the hood let client = PetStore.Client() async { - // Create new instance of provided type and add to store + // Create a new instance of the provided type and add it to the store let pet = PetStore.Pet(Id = Some(24L), Name = "Shani") do! client.AddPet(pet)