[csharp C#] cleanup documentation (#15305)

* [C# csharp] fix documentation of API authorization in README files fix hierarchy level + add internal links + align wording across generators * [C# csharp] fix anchor links in documentation
OpenAPITools · May 10, 2023 · f9937e7 · f9937e7
1 parent ef5dc1c
commit f9937e7
Show file tree

Hide file tree

Showing 109 changed files with 760 additions and 765 deletions.
diff --git a/modules/openapi-generator/src/main/resources/csharp-dotnet2/README.mustache b/modules/openapi-generator/src/main/resources/csharp-dotnet2/README.mustache
@@ -16,19 +16,19 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
     For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
 {{/infoUrl}}
 
-<a name="frameworks-supported"></a>
+<a id="frameworks-supported"></a>
 ## Frameworks supported
 - .NET 2.0
 
-<a name="dependencies"></a>
+<a id="dependencies"></a>
 ## Dependencies
 - Mono compiler
 - Newtonsoft.Json.7.0.1
 - RestSharp.Net2.1.1.11
 
 Note: NuGet is downloaded by the mono compilation script and packages are installed with it. No dependency DLLs are bundled with this generator
 
-<a name="installation"></a>
+<a id="installation"></a>
 ## Installation
 Run the following command to generate the DLL
 - [Mac/Linux] `/bin/sh compile-mono.sh`
@@ -40,7 +40,7 @@ using {{apiPackage}};
 using {{clientPackage}};
 using {{modelPackage}};
 ```
-<a name="getting-started"></a>
+<a id="getting-started"></a>
 ## Getting Started
 
 ```csharp
@@ -110,7 +110,7 @@ namespace Example
 }{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
 ```
 
-<a name="documentation-for-api-endpoints"></a>
+<a id="documentation-for-api-endpoints"></a>
 ## Documentation for API Endpoints
 
 All URIs are relative to *{{{basePath}}}*
@@ -120,7 +120,7 @@ Class | Method | HTTP request | Description
 {{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
 {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
 
-<a name="documentation-for-models"></a>
+<a id="documentation-for-models"></a>
 ## Documentation for Models
 
 {{#modelPackage}}
@@ -131,19 +131,13 @@ Class | Method | HTTP request | Description
 No model defined in this package
 {{/modelPackage}}
 
-<a name="documentation-for-authorization"></a>
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}
-All endpoints do not require authorization.
-{{/authMethods}}
-{{#authMethods}}
-{{#-last}}
-Authentication schemes defined for the API:
-{{/-last}}
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-<a name="{{name}}"></a>
+<a id="{{name}}"></a>
 ### {{name}}
 
 {{#isApiKey}}

diff --git a/modules/openapi-generator/src/main/resources/csharp-dotnet2/api_doc.mustache b/modules/openapi-generator/src/main/resources/csharp-dotnet2/api_doc.mustache
@@ -10,7 +10,7 @@ Method | HTTP request | Description
 
 {{#operations}}
 {{#operation}}
-<a name="{{{operationIdLowerCase}}}"></a>
+<a id="{{{operationIdLowerCase}}}"></a>
 # **{{{operationId}}}**
 > {{{returnType}}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
 

diff --git a/modules/openapi-generator/src/main/resources/csharp-netcore-functions/api_doc.mustache b/modules/openapi-generator/src/main/resources/csharp-netcore-functions/api_doc.mustache
@@ -10,7 +10,7 @@ Method | HTTP request | Description
 
 {{#operations}}
 {{#operation}}
-<a name="{{{operationIdLowerCase}}}"></a>
+<a id="{{{operationIdLowerCase}}}"></a>
 # **{{{operationId}}}**
 > {{#returnType}}{{returnType}}{{/returnType}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
 

diff --git a/modules/openapi-generator/src/main/resources/csharp-netcore/README.mustache b/modules/openapi-generator/src/main/resources/csharp-netcore/README.mustache
@@ -16,15 +16,15 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
     For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
 {{/infoUrl}}
 
-<a name="frameworks-supported"></a>
+<a id="frameworks-supported"></a>
 ## Frameworks supported
 {{#netStandard}}
 - .NET Core >=1.0
 - .NET Framework >=4.6
 - Mono/Xamarin >=vNext
 {{/netStandard}}
 
-<a name="dependencies"></a>
+<a id="dependencies"></a>
 ## Dependencies
 
 {{#useRestSharp}}
@@ -59,7 +59,7 @@ NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploa
 NOTE: RestSharp for .Net Core creates a new socket for each api call, which can lead to a socket exhaustion problem. See [RestSharp#1406](https://github.com/restsharp/RestSharp/issues/1406).
 
 {{/useRestSharp}}
-<a name="installation"></a>
+<a id="installation"></a>
 ## Installation
 {{#netStandard}}
 Generate the DLL using your preferred tool (e.g. `dotnet build`)
@@ -77,7 +77,7 @@ using {{packageName}}.Client;
 using {{packageName}}.{{modelPackage}};
 ```
 {{^netStandard}}
-<a name="packaging"></a>
+<a id="packaging"></a>
 ## Packaging
 
 A `.nuspec` is included with the project. You can follow the Nuget quickstart to [create](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package#create-the-package) and [publish](https://docs.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package#publish-the-package) packages.
@@ -91,7 +91,7 @@ nuget pack -Build -OutputDirectory out {{packageName}}.csproj
 Then, publish to a [local feed](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds) or [other host](https://docs.microsoft.com/en-us/nuget/hosting-packages/overview) and consume the new package via Nuget as usual.
 
 {{/netStandard}}
-<a name="usage"></a>
+<a id="usage"></a>
 ## Usage
 
 To use the API client with a HTTP proxy, setup a `System.Net.WebProxy`
@@ -131,7 +131,7 @@ services.AddHttpClient<YourApiClass>(httpClient =>
 
 {{/useHttpClient}}
 
-<a name="getting-started"></a>
+<a id="getting-started"></a>
 ## Getting Started
 
 ```csharp
@@ -215,7 +215,7 @@ namespace Example
 }
 ```
 
-<a name="documentation-for-api-endpoints"></a>
+<a id="documentation-for-api-endpoints"></a>
 ## Documentation for API Endpoints
 
 All URIs are relative to *{{{basePath}}}*
@@ -225,7 +225,7 @@ Class | Method | HTTP request | Description
 {{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
 {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
 
-<a name="documentation-for-models"></a>
+<a id="documentation-for-models"></a>
 ## Documentation for Models
 
 {{#modelPackage}}
@@ -236,19 +236,13 @@ Class | Method | HTTP request | Description
 No model defined in this package
 {{/modelPackage}}
 
-<a name="documentation-for-authorization"></a>
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}
-All endpoints do not require authorization.
-{{/authMethods}}
-{{#authMethods}}
-{{#last}}
-Authentication schemes defined for the API:
-{{/last}}
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-<a name="{{name}}"></a>
+<a id="{{name}}"></a>
 ### {{name}}
 
 {{#isApiKey}}- **Type**: API key

diff --git a/modules/openapi-generator/src/main/resources/csharp-netcore/api_doc.mustache b/modules/openapi-generator/src/main/resources/csharp-netcore/api_doc.mustache
@@ -13,7 +13,7 @@ All URIs are relative to *{{{basePath}}}*
 
 {{#operations}}
 {{#operation}}
-<a name="{{{operationIdLowerCase}}}"></a>
+<a id="{{{operationIdLowerCase}}}"></a>
 # **{{{operationId}}}**
 > {{returnType}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
 

diff --git a/...-generator/src/main/resources/csharp-netcore/libraries/generichost/README.client.mustache b/...-generator/src/main/resources/csharp-netcore/libraries/generichost/README.client.mustache
@@ -1,6 +1,6 @@
 # Created with Openapi Generator
 
-<a name="cli"></a>
+<a id="cli"></a>
 ## Run the following powershell command to generate the library
 
 ```ps1
@@ -42,7 +42,7 @@ java -jar "<path>/openapi-generator/modules/openapi-generator-cli/target/openapi
     # -t templates
 ```
 
-<a name="usage"></a>
+<a id="usage"></a>
 ## Using the library in your project
 
 ```cs
@@ -102,7 +102,7 @@ namespace YourProject
     }
 }
 ```
-<a name="questions"></a>
+<a id="questions"></a>
 ## Questions
 
 - What about HttpRequest failures and retries?
@@ -118,7 +118,7 @@ namespace YourProject
   Use the provided On and After methods in the Api class from the namespace {{packageName}}.Rest.DefaultApi.
   Or provide your own class by using the generic Configure{{apiName}} method.
 
-<a name="dependencies"></a>
+<a id="dependencies"></a>
 ## Dependencies
 
 - [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting/) - 5.0.0 or later
@@ -128,7 +128,7 @@ namespace YourProject
 - [CompareNETObjects](https://www.nuget.org/packages/CompareNETObjects) - 4.61.0 or later{{/useCompareNetObjects}}{{#validatable}}
 - [System.ComponentModel.Annotations](https://www.nuget.org/packages/System.ComponentModel.Annotations) - 4.7.0 or later{{/validatable}}{{#apiDocs}}
 
-<a name="documentation-for-api-endpoints"></a>
+<a id="documentation-for-api-endpoints"></a>
 ## Documentation for API Endpoints
 
 All URIs are relative to *{{{basePath}}}*
@@ -137,30 +137,40 @@ Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}
 *{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}{{/apiDocs}}{{#modelDocs}}
 
-<a name="documentation-for-models"></a>
+<a id="documentation-for-models"></a>
 ## Documentation for Models
 
 {{#modelPackage}}{{#models}}{{#model}} - [{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md){{/model}}{{/models}}{{/modelPackage}}
 {{^modelPackage}}No model defined in this package{{/modelPackage}}{{/modelDocs}}
 
-<a name="documentation-for-authorization"></a>
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}All endpoints do not require authorization.{{/authMethods}}{{#authMethods}}{{#-last}}Authentication schemes defined for the API:{{/-last}}{{/authMethods}}{{#authMethods}}
-
-<a name="{{name}}"></a>
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
+{{#authMethods}}
+<a id="{{name}}"></a>
 ### {{name}}
 
 {{#isApiKey}}- **Type**: API key
 - **API key parameter name**: {{keyParamName}}
-- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}{{/isApiKey}}{{#isBasicBasic}}
-- **Type**: HTTP basic authentication{{/isBasicBasic}}{{#isBasicBearer}}
-- **Type**: Bearer Authentication{{/isBasicBearer}}{{#isOAuth}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasicBasic}}
+- **Type**: HTTP basic authentication
+{{/isBasicBasic}}
+{{#isBasicBearer}}
+- **Type**: Bearer Authentication
+{{/isBasicBearer}}
+{{#isOAuth}}
 - **Type**: OAuth
 - **Flow**: {{flow}}
 - **Authorization URL**: {{authorizationUrl}}
 - **Scopes**: {{^scopes}}N/A{{/scopes}}{{#scopes}}  
-- {{scope}}: {{description}}{{/scopes}}{{/isOAuth}}{{/authMethods}}
+- {{scope}}: {{description}}{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}
 
 ## Build
 - SDK version: {{packageVersion}}{{^hideGenerationTimestamp}}

diff --git a/...api-generator/src/main/resources/csharp-netcore/libraries/unityWebRequest/README.mustache b/...api-generator/src/main/resources/csharp-netcore/libraries/unityWebRequest/README.mustache
@@ -16,19 +16,19 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
     For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
 {{/infoUrl}}
 
-<a name="version-support"></a>
+<a id="version-support"></a>
 ## Version support
 This generator should support all current LTS versions of Unity
 - Unity 2020.3 (LTS) and up
 - .NET Standard 2.1 / .NET Framework
 
-<a name="dependencies"></a>
+<a id="dependencies"></a>
 ## Dependencies
 
 - [Newtonsoft.Json](https://docs.unity3d.com/Packages/[email protected]/manual/index.html) - 3.0.2 or later
 - [Unity Test Framework](https://docs.unity3d.com/Packages/[email protected]/manual/index.html) - 1.1.33 or later
 
-<a name="installation"></a>
+<a id="installation"></a>
 ## Installation
 Add the dependencies to `Packages/manifest.json`
 ```
@@ -48,7 +48,7 @@ using {{packageName}}.Client;
 using {{packageName}}.{{modelPackage}};
 ```
 
-<a name="getting-started"></a>
+<a id="getting-started"></a>
 ## Getting Started
 
 ```csharp
@@ -123,7 +123,7 @@ namespace {{packageName}}Example
 }
 ```
 
-<a name="documentation-for-api-endpoints"></a>
+<a id="documentation-for-api-endpoints"></a>
 ## Documentation for API Endpoints
 
 All URIs are relative to *{{{basePath}}}*
@@ -133,7 +133,7 @@ Class | Method | HTTP request | Description
 {{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
 {{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
 
-<a name="documentation-for-models"></a>
+<a id="documentation-for-models"></a>
 ## Documentation for Models
 
 {{#modelPackage}}
@@ -144,19 +144,13 @@ Class | Method | HTTP request | Description
 No model defined in this package
 {{/modelPackage}}
 
-<a name="documentation-for-authorization"></a>
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}
-All endpoints do not require authorization.
-{{/authMethods}}
-{{#authMethods}}
-{{#last}}
-Authentication schemes defined for the API:
-{{/last}}
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-<a name="{{name}}"></a>
+<a id="{{name}}"></a>
 ### {{name}}
 
 {{#isApiKey}}- **Type**: API key