Skip to content

Commit c251202

Browse files
tiffmaelitetiffmaelite
authored
[Python] cleanup documentation (#15301)
* [Python] fix documentation of API authorization in README files fix hierarchy level + add internal links + align wording across generators * [Python] fix anchor links in documentation
1 parent da9ad4a commit c251202

55 files changed

Lines changed: 944 additions & 908 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/python-legacy/common_README.mustache‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,14 @@ Class | Method | HTTP request | Description
3838
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
3939
{{/model}}{{/models}}
4040

41+
<a id="documentation-for-authorization"></a>
4142
## Documentation For Authorization
4243

43-
{{^authMethods}}
44-
All endpoints do not require authorization.
45-
{{/authMethods}}
44+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
45+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
4646
{{#authMethods}}
47-
{{#last}} Authentication schemes defined for the API:{{/last}}
48-
## {{{name}}}
47+
<a id="{{name}}"></a>
48+
### {{{name}}}
4949

5050
{{#isApiKey}}
5151
- **Type**: API key

‎modules/openapi-generator/src/main/resources/python-nextgen/common_README.mustache‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,14 +43,14 @@ Class | Method | HTTP request | Description
4343
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
4444
{{/model}}{{/models}}
4545

46+
<a id="documentation-for-authorization"></a>
4647
## Documentation For Authorization
4748

48-
{{^authMethods}}
49-
All endpoints do not require authorization.
50-
{{/authMethods}}
49+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
50+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
5151
{{#authMethods}}
52-
{{#last}} Authentication schemes defined for the API:{{/last}}
53-
## {{{name}}}
52+
<a id="{{name}}"></a>
53+
### {{{name}}}
5454

5555
{{#isApiKey}}
5656
- **Type**: API key

‎modules/openapi-generator/src/main/resources/python-prior/README_common.mustache‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,14 +51,14 @@ Class | Method | HTTP request | Description
5151
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
5252
{{/model}}{{/models}}
5353

54+
<a id="documentation-for-authorization"></a>
5455
## Documentation For Authorization
5556

56-
{{^authMethods}}
57-
All endpoints do not require authorization.
58-
{{/authMethods}}
57+
{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
58+
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
5959
{{#authMethods}}
60-
{{#last}} Authentication schemes defined for the API:{{/last}}
61-
## {{{name}}}
60+
<a id="{{name}}"></a>
61+
### {{{name}}}
6262

6363
{{#isApiKey}}
6464
- **Type**: API key

‎modules/openapi-generator/src/main/resources/python/README_common.handlebars‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,12 @@ Class | Method | HTTP request | Description
5353
## Documentation For Authorization
5454
5555
{{#unless authMethods}}
56-
All endpoints do not require authorization.
56+
Endpoints do not require authorization.
5757
{{/unless}}
58+
{{#if hasAuthMethods}}Authentication schemes defined for the API:{{/if}}
5859
{{#each authMethods}}
59-
{{#if @last}} Authentication schemes defined for the API:{{/if}}
60-
## {{{name}}}
60+
<a id="{{name}}"></a>
61+
### {{{name}}}
6162
6263
{{#if isApiKey}}
6364
- **Type**: API key

‎modules/openapi-generator/src/main/resources/python/api_doc.handlebars‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<a name="__pageTop"></a>
1+
<a id="__pageTop"></a>
22
# {{packageName}}.{{apiPackage}}.tags.{{classFilename}}.{{classname}}{{#if description}}
33
{{description}}{{/if}}
44

@@ -12,7 +12,7 @@ Method | HTTP request | Description
1212
{{#with operations}}
1313
{{#each operation}}
1414
# **{{{operationId}}}**
15-
<a name="{{{operationId}}}"></a>
15+
<a id="{{{operationId}}}"></a>
1616
> {{#if returnType}}{{{returnType}}} {{/if}}{{{operationId}}}({{#each requiredParams}}{{#unless defaultValue}}{{paramName}}{{#if hasMore}}, {{/if}}{{/unless}}{{/each}})
1717
1818
{{#if summary}}{{{summary}}}{{/if}}{{#if notes}}

‎samples/client/echo_api/python-nextgen/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,9 +119,11 @@ Class | Method | HTTP request | Description
119119
- [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
120120

121121

122+
<a id="documentation-for-authorization"></a>
122123
## Documentation For Authorization
123124

124-
All endpoints do not require authorization.
125+
Endpoints do not require authorization.
126+
125127

126128
## Author
127129

‎samples/client/petstore/python-asyncio/README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -172,10 +172,13 @@ Class | Method | HTTP request | Description
172172
- [XmlItem](docs/XmlItem.md)
173173

174174

175+
<a id="documentation-for-authorization"></a>
175176
## Documentation For Authorization
176177

177178

178-
## petstore_auth
179+
Authentication schemes defined for the API:
180+
<a id="petstore_auth"></a>
181+
### petstore_auth
179182

180183
- **Type**: OAuth
181184
- **Flow**: implicit
@@ -184,22 +187,22 @@ Class | Method | HTTP request | Description
184187
- **write:pets**: modify pets in your account
185188
- **read:pets**: read your pets
186189

187-
188-
## api_key
190+
<a id="api_key"></a>
191+
### api_key
189192

190193
- **Type**: API key
191194
- **API key parameter name**: api_key
192195
- **Location**: HTTP header
193196

194-
195-
## api_key_query
197+
<a id="api_key_query"></a>
198+
### api_key_query
196199

197200
- **Type**: API key
198201
- **API key parameter name**: api_key_query
199202
- **Location**: URL query string
200203

201-
202-
## http_basic_test
204+
<a id="http_basic_test"></a>
205+
### http_basic_test
203206

204207
- **Type**: HTTP basic authentication
205208

‎samples/client/petstore/python-legacy/README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -172,10 +172,13 @@ Class | Method | HTTP request | Description
172172
- [XmlItem](docs/XmlItem.md)
173173

174174

175+
<a id="documentation-for-authorization"></a>
175176
## Documentation For Authorization
176177

177178

178-
## petstore_auth
179+
Authentication schemes defined for the API:
180+
<a id="petstore_auth"></a>
181+
### petstore_auth
179182

180183
- **Type**: OAuth
181184
- **Flow**: implicit
@@ -184,22 +187,22 @@ Class | Method | HTTP request | Description
184187
- **write:pets**: modify pets in your account
185188
- **read:pets**: read your pets
186189

187-
188-
## api_key
190+
<a id="api_key"></a>
191+
### api_key
189192

190193
- **Type**: API key
191194
- **API key parameter name**: api_key
192195
- **Location**: HTTP header
193196

194-
195-
## api_key_query
197+
<a id="api_key_query"></a>
198+
### api_key_query
196199

197200
- **Type**: API key
198201
- **API key parameter name**: api_key_query
199202
- **Location**: URL query string
200203

201-
202-
## http_basic_test
204+
<a id="http_basic_test"></a>
205+
### http_basic_test
203206

204207
- **Type**: HTTP basic authentication
205208

‎samples/client/petstore/python-prior/README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -196,10 +196,13 @@ Class | Method | HTTP request | Description
196196
- [XmlItem](docs/XmlItem.md)
197197

198198

199+
<a id="documentation-for-authorization"></a>
199200
## Documentation For Authorization
200201

201202

202-
## petstore_auth
203+
Authentication schemes defined for the API:
204+
<a id="petstore_auth"></a>
205+
### petstore_auth
203206

204207
- **Type**: OAuth
205208
- **Flow**: implicit
@@ -208,22 +211,22 @@ Class | Method | HTTP request | Description
208211
- **write:pets**: modify pets in your account
209212
- **read:pets**: read your pets
210213

211-
212-
## api_key
214+
<a id="api_key"></a>
215+
### api_key
213216

214217
- **Type**: API key
215218
- **API key parameter name**: api_key
216219
- **Location**: HTTP header
217220

218-
219-
## api_key_query
221+
<a id="api_key_query"></a>
222+
### api_key_query
220223

221224
- **Type**: API key
222225
- **API key parameter name**: api_key_query
223226
- **Location**: URL query string
224227

225-
226-
## http_basic_test
228+
<a id="http_basic_test"></a>
229+
### http_basic_test
227230

228231
- **Type**: HTTP basic authentication
229232

‎samples/client/petstore/python-prior_disallowAdditionalPropertiesIfNotPresent/README.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -196,10 +196,13 @@ Class | Method | HTTP request | Description
196196
- [XmlItem](docs/XmlItem.md)
197197

198198

199+
<a id="documentation-for-authorization"></a>
199200
## Documentation For Authorization
200201

201202

202-
## petstore_auth
203+
Authentication schemes defined for the API:
204+
<a id="petstore_auth"></a>
205+
### petstore_auth
203206

204207
- **Type**: OAuth
205208
- **Flow**: implicit
@@ -208,22 +211,22 @@ Class | Method | HTTP request | Description
208211
- **write:pets**: modify pets in your account
209212
- **read:pets**: read your pets
210213

211-
212-
## api_key
214+
<a id="api_key"></a>
215+
### api_key
213216

214217
- **Type**: API key
215218
- **API key parameter name**: api_key
216219
- **Location**: HTTP header
217220

218-
219-
## api_key_query
221+
<a id="api_key_query"></a>
222+
### api_key_query
220223

221224
- **Type**: API key
222225
- **API key parameter name**: api_key_query
223226
- **Location**: URL query string
224227

225-
226-
## http_basic_test
228+
<a id="http_basic_test"></a>
229+
### http_basic_test
227230

228231
- **Type**: HTTP basic authentication
229232

0 commit comments

Comments
 (0)