Skip to content

Commit f9937e7

Browse files
tiffmaelitetiffmaelite
authored
[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
1 parent ef5dc1c commit f9937e7

109 files changed

Lines changed: 760 additions & 765 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎modules/openapi-generator/src/main/resources/csharp-dotnet2/README.mustache‎

Lines changed: 10 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,19 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
1616
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
1717
{{/infoUrl}}
1818

19-
<a name="frameworks-supported"></a>
19+
<a id="frameworks-supported"></a>
2020
## Frameworks supported
2121
- .NET 2.0
2222

23-
<a name="dependencies"></a>
23+
<a id="dependencies"></a>
2424
## Dependencies
2525
- Mono compiler
2626
- Newtonsoft.Json.7.0.1
2727
- RestSharp.Net2.1.1.11
2828

2929
Note: NuGet is downloaded by the mono compilation script and packages are installed with it. No dependency DLLs are bundled with this generator
3030

31-
<a name="installation"></a>
31+
<a id="installation"></a>
3232
## Installation
3333
Run the following command to generate the DLL
3434
- [Mac/Linux] `/bin/sh compile-mono.sh`
@@ -40,7 +40,7 @@ using {{apiPackage}};
4040
using {{clientPackage}};
4141
using {{modelPackage}};
4242
```
43-
<a name="getting-started"></a>
43+
<a id="getting-started"></a>
4444
## Getting Started
4545

4646
```csharp
@@ -110,7 +110,7 @@ namespace Example
110110
}{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
111111
```
112112

113-
<a name="documentation-for-api-endpoints"></a>
113+
<a id="documentation-for-api-endpoints"></a>
114114
## Documentation for API Endpoints
115115

116116
All URIs are relative to *{{{basePath}}}*
@@ -120,7 +120,7 @@ Class | Method | HTTP request | Description
120120
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
121121
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
122122

123-
<a name="documentation-for-models"></a>
123+
<a id="documentation-for-models"></a>
124124
## Documentation for Models
125125

126126
{{#modelPackage}}
@@ -131,19 +131,13 @@ Class | Method | HTTP request | Description
131131
No model defined in this package
132132
{{/modelPackage}}
133133

134-
<a name="documentation-for-authorization"></a>
134+
<a id="documentation-for-authorization"></a>
135135
## Documentation for Authorization
136136

137-
{{^authMethods}}
138-
All endpoints do not require authorization.
139-
{{/authMethods}}
140-
{{#authMethods}}
141-
{{#-last}}
142-
Authentication schemes defined for the API:
143-
{{/-last}}
144-
{{/authMethods}}
137+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
138+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
145139
{{#authMethods}}
146-
<a name="{{name}}"></a>
140+
<a id="{{name}}"></a>
147141
### {{name}}
148142

149143
{{#isApiKey}}

‎modules/openapi-generator/src/main/resources/csharp-dotnet2/api_doc.mustache‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Method | HTTP request | Description
1010

1111
{{#operations}}
1212
{{#operation}}
13-
<a name="{{{operationIdLowerCase}}}"></a>
13+
<a id="{{{operationIdLowerCase}}}"></a>
1414
# **{{{operationId}}}**
1515
> {{{returnType}}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
1616

‎modules/openapi-generator/src/main/resources/csharp-netcore-functions/api_doc.mustache‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Method | HTTP request | Description
1010

1111
{{#operations}}
1212
{{#operation}}
13-
<a name="{{{operationIdLowerCase}}}"></a>
13+
<a id="{{{operationIdLowerCase}}}"></a>
1414
# **{{{operationId}}}**
1515
> {{#returnType}}{{returnType}}{{/returnType}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
1616

‎modules/openapi-generator/src/main/resources/csharp-netcore/README.mustache‎

Lines changed: 12 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,15 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
1616
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
1717
{{/infoUrl}}
1818

19-
<a name="frameworks-supported"></a>
19+
<a id="frameworks-supported"></a>
2020
## Frameworks supported
2121
{{#netStandard}}
2222
- .NET Core >=1.0
2323
- .NET Framework >=4.6
2424
- Mono/Xamarin >=vNext
2525
{{/netStandard}}
2626

27-
<a name="dependencies"></a>
27+
<a id="dependencies"></a>
2828
## Dependencies
2929

3030
{{#useRestSharp}}
@@ -59,7 +59,7 @@ NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploa
5959
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).
6060

6161
{{/useRestSharp}}
62-
<a name="installation"></a>
62+
<a id="installation"></a>
6363
## Installation
6464
{{#netStandard}}
6565
Generate the DLL using your preferred tool (e.g. `dotnet build`)
@@ -77,7 +77,7 @@ using {{packageName}}.Client;
7777
using {{packageName}}.{{modelPackage}};
7878
```
7979
{{^netStandard}}
80-
<a name="packaging"></a>
80+
<a id="packaging"></a>
8181
## Packaging
8282

8383
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
9191
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.
9292

9393
{{/netStandard}}
94-
<a name="usage"></a>
94+
<a id="usage"></a>
9595
## Usage
9696

9797
To use the API client with a HTTP proxy, setup a `System.Net.WebProxy`
@@ -131,7 +131,7 @@ services.AddHttpClient<YourApiClass>(httpClient =>
131131

132132
{{/useHttpClient}}
133133

134-
<a name="getting-started"></a>
134+
<a id="getting-started"></a>
135135
## Getting Started
136136

137137
```csharp
@@ -215,7 +215,7 @@ namespace Example
215215
}
216216
```
217217

218-
<a name="documentation-for-api-endpoints"></a>
218+
<a id="documentation-for-api-endpoints"></a>
219219
## Documentation for API Endpoints
220220

221221
All URIs are relative to *{{{basePath}}}*
@@ -225,7 +225,7 @@ Class | Method | HTTP request | Description
225225
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
226226
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
227227

228-
<a name="documentation-for-models"></a>
228+
<a id="documentation-for-models"></a>
229229
## Documentation for Models
230230

231231
{{#modelPackage}}
@@ -236,19 +236,13 @@ Class | Method | HTTP request | Description
236236
No model defined in this package
237237
{{/modelPackage}}
238238

239-
<a name="documentation-for-authorization"></a>
239+
<a id="documentation-for-authorization"></a>
240240
## Documentation for Authorization
241241

242-
{{^authMethods}}
243-
All endpoints do not require authorization.
244-
{{/authMethods}}
245-
{{#authMethods}}
246-
{{#last}}
247-
Authentication schemes defined for the API:
248-
{{/last}}
249-
{{/authMethods}}
242+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
243+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
250244
{{#authMethods}}
251-
<a name="{{name}}"></a>
245+
<a id="{{name}}"></a>
252246
### {{name}}
253247

254248
{{#isApiKey}}- **Type**: API key

‎modules/openapi-generator/src/main/resources/csharp-netcore/api_doc.mustache‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ All URIs are relative to *{{{basePath}}}*
1313

1414
{{#operations}}
1515
{{#operation}}
16-
<a name="{{{operationIdLowerCase}}}"></a>
16+
<a id="{{{operationIdLowerCase}}}"></a>
1717
# **{{{operationId}}}**
1818
> {{returnType}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
1919

‎modules/openapi-generator/src/main/resources/csharp-netcore/libraries/generichost/README.client.mustache‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Created with Openapi Generator
22

3-
<a name="cli"></a>
3+
<a id="cli"></a>
44
## Run the following powershell command to generate the library
55

66
```ps1
@@ -42,7 +42,7 @@ java -jar "<path>/openapi-generator/modules/openapi-generator-cli/target/openapi
4242
# -t templates
4343
```
4444

45-
<a name="usage"></a>
45+
<a id="usage"></a>
4646
## Using the library in your project
4747

4848
```cs
@@ -102,7 +102,7 @@ namespace YourProject
102102
}
103103
}
104104
```
105-
<a name="questions"></a>
105+
<a id="questions"></a>
106106
## Questions
107107

108108
- What about HttpRequest failures and retries?
@@ -118,7 +118,7 @@ namespace YourProject
118118
Use the provided On and After methods in the Api class from the namespace {{packageName}}.Rest.DefaultApi.
119119
Or provide your own class by using the generic Configure{{apiName}} method.
120120

121-
<a name="dependencies"></a>
121+
<a id="dependencies"></a>
122122
## Dependencies
123123

124124
- [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting/) - 5.0.0 or later
@@ -128,7 +128,7 @@ namespace YourProject
128128
- [CompareNETObjects](https://www.nuget.org/packages/CompareNETObjects) - 4.61.0 or later{{/useCompareNetObjects}}{{#validatable}}
129129
- [System.ComponentModel.Annotations](https://www.nuget.org/packages/System.ComponentModel.Annotations) - 4.7.0 or later{{/validatable}}{{#apiDocs}}
130130

131-
<a name="documentation-for-api-endpoints"></a>
131+
<a id="documentation-for-api-endpoints"></a>
132132
## Documentation for API Endpoints
133133

134134
All URIs are relative to *{{{basePath}}}*
@@ -137,30 +137,40 @@ Class | Method | HTTP request | Description
137137
------------ | ------------- | ------------- | -------------{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}
138138
*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}{{/apiDocs}}{{#modelDocs}}
139139

140-
<a name="documentation-for-models"></a>
140+
<a id="documentation-for-models"></a>
141141
## Documentation for Models
142142

143143
{{#modelPackage}}{{#models}}{{#model}} - [{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md){{/model}}{{/models}}{{/modelPackage}}
144144
{{^modelPackage}}No model defined in this package{{/modelPackage}}{{/modelDocs}}
145145

146-
<a name="documentation-for-authorization"></a>
146+
<a id="documentation-for-authorization"></a>
147147
## Documentation for Authorization
148148

149-
{{^authMethods}}All endpoints do not require authorization.{{/authMethods}}{{#authMethods}}{{#-last}}Authentication schemes defined for the API:{{/-last}}{{/authMethods}}{{#authMethods}}
150-
151-
<a name="{{name}}"></a>
149+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
150+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
151+
{{#authMethods}}
152+
<a id="{{name}}"></a>
152153
### {{name}}
153154

154155
{{#isApiKey}}- **Type**: API key
155156
- **API key parameter name**: {{keyParamName}}
156-
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}{{/isApiKey}}{{#isBasicBasic}}
157-
- **Type**: HTTP basic authentication{{/isBasicBasic}}{{#isBasicBearer}}
158-
- **Type**: Bearer Authentication{{/isBasicBearer}}{{#isOAuth}}
157+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
158+
{{/isApiKey}}
159+
{{#isBasicBasic}}
160+
- **Type**: HTTP basic authentication
161+
{{/isBasicBasic}}
162+
{{#isBasicBearer}}
163+
- **Type**: Bearer Authentication
164+
{{/isBasicBearer}}
165+
{{#isOAuth}}
159166
- **Type**: OAuth
160167
- **Flow**: {{flow}}
161168
- **Authorization URL**: {{authorizationUrl}}
162169
- **Scopes**: {{^scopes}}N/A{{/scopes}}{{#scopes}}
163-
- {{scope}}: {{description}}{{/scopes}}{{/isOAuth}}{{/authMethods}}
170+
- {{scope}}: {{description}}{{/scopes}}
171+
{{/isOAuth}}
172+
173+
{{/authMethods}}
164174

165175
## Build
166176
- SDK version: {{packageVersion}}{{^hideGenerationTimestamp}}

‎modules/openapi-generator/src/main/resources/csharp-netcore/libraries/unityWebRequest/README.mustache‎

Lines changed: 10 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,19 @@ This C# SDK is automatically generated by the [OpenAPI Generator](https://openap
1616
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
1717
{{/infoUrl}}
1818

19-
<a name="version-support"></a>
19+
<a id="version-support"></a>
2020
## Version support
2121
This generator should support all current LTS versions of Unity
2222
- Unity 2020.3 (LTS) and up
2323
- .NET Standard 2.1 / .NET Framework
2424

25-
<a name="dependencies"></a>
25+
<a id="dependencies"></a>
2626
## Dependencies
2727

2828
- [Newtonsoft.Json](https://docs.unity3d.com/Packages/com.unity.nuget.newtonsoft-json@3.0/manual/index.html) - 3.0.2 or later
2929
- [Unity Test Framework](https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/manual/index.html) - 1.1.33 or later
3030

31-
<a name="installation"></a>
31+
<a id="installation"></a>
3232
## Installation
3333
Add the dependencies to `Packages/manifest.json`
3434
```
@@ -48,7 +48,7 @@ using {{packageName}}.Client;
4848
using {{packageName}}.{{modelPackage}};
4949
```
5050

51-
<a name="getting-started"></a>
51+
<a id="getting-started"></a>
5252
## Getting Started
5353

5454
```csharp
@@ -123,7 +123,7 @@ namespace {{packageName}}Example
123123
}
124124
```
125125

126-
<a name="documentation-for-api-endpoints"></a>
126+
<a id="documentation-for-api-endpoints"></a>
127127
## Documentation for API Endpoints
128128

129129
All URIs are relative to *{{{basePath}}}*
@@ -133,7 +133,7 @@ Class | Method | HTTP request | Description
133133
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
134134
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
135135

136-
<a name="documentation-for-models"></a>
136+
<a id="documentation-for-models"></a>
137137
## Documentation for Models
138138

139139
{{#modelPackage}}
@@ -144,19 +144,13 @@ Class | Method | HTTP request | Description
144144
No model defined in this package
145145
{{/modelPackage}}
146146

147-
<a name="documentation-for-authorization"></a>
147+
<a id="documentation-for-authorization"></a>
148148
## Documentation for Authorization
149149

150-
{{^authMethods}}
151-
All endpoints do not require authorization.
152-
{{/authMethods}}
153-
{{#authMethods}}
154-
{{#last}}
155-
Authentication schemes defined for the API:
156-
{{/last}}
157-
{{/authMethods}}
150+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
151+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
158152
{{#authMethods}}
159-
<a name="{{name}}"></a>
153+
<a id="{{name}}"></a>
160154
### {{name}}
161155

162156
{{#isApiKey}}- **Type**: API key

0 commit comments

Comments
 (0)