[Java] Cleanup documentation (#15300)

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

Hide file tree

Showing 99 changed files with 527 additions and 347 deletions.
diff --git a/modules/openapi-generator/src/main/resources/Java/README.mustache b/modules/openapi-generator/src/main/resources/Java/README.mustache
@@ -197,11 +197,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}All endpoints do not require authorization.
-{{/authMethods}}Authentication schemes defined for the API:
-{{#authMethods}}### {{name}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
+{{#authMethods}}
+<a id="{{name}}"></a>
+### {{name}}
 
 {{#isApiKey}}
 

diff --git a/...les/openapi-generator/src/main/resources/Java/libraries/apache-httpclient/README.mustache b/...les/openapi-generator/src/main/resources/Java/libraries/apache-httpclient/README.mustache
@@ -158,11 +158,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}All endpoints do not require authorization.
-{{/authMethods}}Authentication schemes defined for the API:
-{{#authMethods}}### {{name}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
+{{#authMethods}}
+<a id="{{name}}"></a>
+### {{name}}
 
 {{#isApiKey}}
 

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/native/README.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/native/README.mustache
@@ -139,11 +139,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}All endpoints do not require authorization.
-{{/authMethods}}Authentication schemes defined for the API:
-{{#authMethods}}### {{name}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
+{{#authMethods}}
+<a id="{{name}}"></a>
+### {{name}}
 
 {{#isApiKey}}
 

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/native/api_doc.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/native/api_doc.mustache
@@ -266,7 +266,7 @@ public class Example {
 {{/responses.0}}
 {{#vendorExtensions.x-group-parameters}}{{#hasParams}}
 
-<a name="API{{operationId}}Request"></a>
+<a id="API{{operationId}}Request"></a>
 ## API{{operationId}}Request
 ### Properties
 {{#allParams}}{{#-last}}

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/README.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/README.mustache
@@ -155,11 +155,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-{{^authMethods}}All endpoints do not require authorization.
-{{/authMethods}}Authentication schemes defined for the API:
-{{#authMethods}}### {{name}}
+{{^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}}

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/api_doc.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/api_doc.mustache
@@ -10,7 +10,7 @@ All URIs are relative to *{{basePath}}*
 
 {{#operations}}
 {{#operation}}
-<a name="{{operationId}}"></a>
+<a id="{{operationId}}"></a>
 # **{{operationId}}**{{^vendorExtensions.x-group-parameters}}
 > {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}}){{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}
 > {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#requiredParams}}{{paramName}}{{^-last}}, {{/-last}}{{/requiredParams}}){{#optionalParams}}.{{paramName}}({{paramName}}){{/optionalParams}}.execute();{{/vendorExtensions.x-group-parameters}}

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/rest-assured/api_doc.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/rest-assured/api_doc.mustache
@@ -10,7 +10,7 @@ All URIs are relative to *{{basePath}}*
 
 {{#operations}}
 {{#operation}}
-<a name="{{operationId}}"></a>
+<a id="{{operationId}}"></a>
 # **{{operationId}}**
 > {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}})
 

diff --git a/modules/openapi-generator/src/main/resources/java-micronaut/client/doc/api_doc.mustache b/modules/openapi-generator/src/main/resources/java-micronaut/client/doc/api_doc.mustache
@@ -38,7 +38,7 @@ More information can be found inside [Inversion of Control guide section](https:
 
 {{#operations}}
 {{#operation}}
-<a name="{{operationId}}"></a>
+<a id="{{operationId}}"></a>
 # **{{operationId}}**
 ```java
 {{#returnType}}Mono<{{{returnType}}}>{{/returnType}}{{^returnType}}Mono<Void>{{/returnType}} {{classname}}.{{nickname}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}})

diff --git a/modules/openapi-generator/src/main/resources/java-micronaut/client/doc/auth.mustache b/modules/openapi-generator/src/main/resources/java-micronaut/client/doc/auth.mustache
@@ -1,6 +1,6 @@
 # Authorization methods
 {{#authMethods}}
-<a name="name"></a>
+<a id="name"></a>
 # {{name}}
 {{!
     basic auth

diff --git a/...es/openapi-generator/src/main/resources/java-micronaut/server/doc/controller_doc.mustache b/...es/openapi-generator/src/main/resources/java-micronaut/server/doc/controller_doc.mustache
@@ -15,7 +15,7 @@ Method | HTTP request | Description
 
 {{#operations}}
     {{#operation}}
-<a name="{{operationId}}"></a>
+<a id="{{operationId}}"></a>
 # **{{operationId}}**
 ```java
 {{#returnType}}Mono<{{{returnType}}}>{{/returnType}}{{^returnType}}Mono<Object>{{/returnType}} {{classname}}.{{nickname}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}})

diff --git a/samples/client/echo_api/java/apache-httpclient/README.md b/samples/client/echo_api/java/apache-httpclient/README.md
@@ -140,10 +140,11 @@ Class | Method | HTTP request | Description
  - [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-All endpoints do not require authorization.
-Authentication schemes defined for the API:
+Endpoints do not require authorization.
+
 
 ## Recommendation
 

diff --git a/samples/client/echo_api/java/native/README.md b/samples/client/echo_api/java/native/README.md
@@ -156,10 +156,11 @@ Class | Method | HTTP request | Description
  - [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-All endpoints do not require authorization.
-Authentication schemes defined for the API:
+Endpoints do not require authorization.
+
 
 ## Recommendation
 

diff --git a/samples/client/echo_api/java/okhttp-gson/README.md b/samples/client/echo_api/java/okhttp-gson/README.md
@@ -147,10 +147,11 @@ Class | Method | HTTP request | Description
  - [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-All endpoints do not require authorization.
-Authentication schemes defined for the API:
+Endpoints do not require authorization.
+
 
 ## Recommendation
 

diff --git a/samples/client/echo_api/java/okhttp-gson/docs/BodyApi.md b/samples/client/echo_api/java/okhttp-gson/docs/BodyApi.md
@@ -12,7 +12,7 @@ All URIs are relative to *http://localhost:3000*
 | [**testEchoBodyTagResponseString**](BodyApi.md#testEchoBodyTagResponseString) | **POST** /echo/body/Tag/response_string | Test empty json (request body) |
 
 
-<a name="testBinaryGif"></a>
+<a id="testBinaryGif"></a>
 # **testBinaryGif**
 > File testBinaryGif()
 
@@ -70,7 +70,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testBodyApplicationOctetstreamBinary"></a>
+<a id="testBodyApplicationOctetstreamBinary"></a>
 # **testBodyApplicationOctetstreamBinary**
 > String testBodyApplicationOctetstreamBinary(body)
 
@@ -132,7 +132,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testEchoBodyFreeFormObjectResponseString"></a>
+<a id="testEchoBodyFreeFormObjectResponseString"></a>
 # **testEchoBodyFreeFormObjectResponseString**
 > String testEchoBodyFreeFormObjectResponseString(body)
 
@@ -194,7 +194,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testEchoBodyPet"></a>
+<a id="testEchoBodyPet"></a>
 # **testEchoBodyPet**
 > Pet testEchoBodyPet(pet)
 
@@ -256,7 +256,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testEchoBodyPetResponseString"></a>
+<a id="testEchoBodyPetResponseString"></a>
 # **testEchoBodyPetResponseString**
 > String testEchoBodyPetResponseString(pet)
 
@@ -318,7 +318,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testEchoBodyTagResponseString"></a>
+<a id="testEchoBodyTagResponseString"></a>
 # **testEchoBodyTagResponseString**
 > String testEchoBodyTagResponseString(tag)
 

diff --git a/samples/client/echo_api/java/okhttp-gson/docs/FormApi.md b/samples/client/echo_api/java/okhttp-gson/docs/FormApi.md
@@ -7,7 +7,7 @@ All URIs are relative to *http://localhost:3000*
 | [**testFormIntegerBooleanString**](FormApi.md#testFormIntegerBooleanString) | **POST** /form/integer/boolean/string | Test form parameter(s) |
 
 
-<a name="testFormIntegerBooleanString"></a>
+<a id="testFormIntegerBooleanString"></a>
 # **testFormIntegerBooleanString**
 > String testFormIntegerBooleanString(integerForm, booleanForm, stringForm)
 

diff --git a/samples/client/echo_api/java/okhttp-gson/docs/HeaderApi.md b/samples/client/echo_api/java/okhttp-gson/docs/HeaderApi.md
@@ -7,7 +7,7 @@ All URIs are relative to *http://localhost:3000*
 | [**testHeaderIntegerBooleanString**](HeaderApi.md#testHeaderIntegerBooleanString) | **GET** /header/integer/boolean/string | Test header parameter(s) |
 
 
-<a name="testHeaderIntegerBooleanString"></a>
+<a id="testHeaderIntegerBooleanString"></a>
 # **testHeaderIntegerBooleanString**
 > String testHeaderIntegerBooleanString(integerHeader, booleanHeader, stringHeader)
 

diff --git a/samples/client/echo_api/java/okhttp-gson/docs/PathApi.md b/samples/client/echo_api/java/okhttp-gson/docs/PathApi.md
@@ -7,7 +7,7 @@ All URIs are relative to *http://localhost:3000*
 | [**testsPathStringPathStringIntegerPathInteger**](PathApi.md#testsPathStringPathStringIntegerPathInteger) | **GET** /path/string/{path_string}/integer/{path_integer} | Test path parameter(s) |
 
 
-<a name="testsPathStringPathStringIntegerPathInteger"></a>
+<a id="testsPathStringPathStringIntegerPathInteger"></a>
 # **testsPathStringPathStringIntegerPathInteger**
 > String testsPathStringPathStringIntegerPathInteger(pathString, pathInteger)
 

diff --git a/samples/client/echo_api/java/okhttp-gson/docs/QueryApi.md b/samples/client/echo_api/java/okhttp-gson/docs/QueryApi.md
@@ -14,7 +14,7 @@ All URIs are relative to *http://localhost:3000*
 | [**testQueryStyleFormExplodeTrueObjectAllOf**](QueryApi.md#testQueryStyleFormExplodeTrueObjectAllOf) | **GET** /query/style_form/explode_true/object/allOf | Test query parameter(s) |
 
 
-<a name="testEnumRefString"></a>
+<a id="testEnumRefString"></a>
 # **testEnumRefString**
 > String testEnumRefString(enumRefStringQuery)
 
@@ -76,7 +76,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryDatetimeDateString"></a>
+<a id="testQueryDatetimeDateString"></a>
 # **testQueryDatetimeDateString**
 > String testQueryDatetimeDateString(datetimeQuery, dateQuery, stringQuery)
 
@@ -142,7 +142,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryIntegerBooleanString"></a>
+<a id="testQueryIntegerBooleanString"></a>
 # **testQueryIntegerBooleanString**
 > String testQueryIntegerBooleanString(integerQuery, booleanQuery, stringQuery)
 
@@ -208,7 +208,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryStyleDeepObjectExplodeTrueObject"></a>
+<a id="testQueryStyleDeepObjectExplodeTrueObject"></a>
 # **testQueryStyleDeepObjectExplodeTrueObject**
 > String testQueryStyleDeepObjectExplodeTrueObject(queryObject)
 
@@ -270,7 +270,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryStyleDeepObjectExplodeTrueObjectAllOf"></a>
+<a id="testQueryStyleDeepObjectExplodeTrueObjectAllOf"></a>
 # **testQueryStyleDeepObjectExplodeTrueObjectAllOf**
 > String testQueryStyleDeepObjectExplodeTrueObjectAllOf(queryObject)
 
@@ -332,7 +332,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryStyleFormExplodeTrueArrayString"></a>
+<a id="testQueryStyleFormExplodeTrueArrayString"></a>
 # **testQueryStyleFormExplodeTrueArrayString**
 > String testQueryStyleFormExplodeTrueArrayString(queryObject)
 
@@ -394,7 +394,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryStyleFormExplodeTrueObject"></a>
+<a id="testQueryStyleFormExplodeTrueObject"></a>
 # **testQueryStyleFormExplodeTrueObject**
 > String testQueryStyleFormExplodeTrueObject(queryObject)
 
@@ -456,7 +456,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | Successful operation |  -  |
 
-<a name="testQueryStyleFormExplodeTrueObjectAllOf"></a>
+<a id="testQueryStyleFormExplodeTrueObjectAllOf"></a>
 # **testQueryStyleFormExplodeTrueObjectAllOf**
 > String testQueryStyleFormExplodeTrueObjectAllOf(queryObject)
 

diff --git a/samples/client/others/java/okhttp-gson-streaming/README.md b/samples/client/others/java/okhttp-gson-streaming/README.md
@@ -127,10 +127,11 @@ Class | Method | HTTP request | Description
  - [SomeObj](docs/SomeObj.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation for Authorization
 
-All endpoints do not require authorization.
-Authentication schemes defined for the API:
+Endpoints do not require authorization.
+
 
 ## Recommendation
 

diff --git a/samples/client/others/java/okhttp-gson-streaming/docs/PingApi.md b/samples/client/others/java/okhttp-gson-streaming/docs/PingApi.md
@@ -8,7 +8,7 @@ All URIs are relative to *http://localhost:8082*
 | [**postPing**](PingApi.md#postPing) | **POST** /ping |  |
 
 
-<a name="getPing"></a>
+<a id="getPing"></a>
 # **getPing**
 > SomeObj getPing(petId).name(name).status(status).execute();
 
@@ -75,7 +75,7 @@ No authorization required
 |-------------|-------------|------------------|
 | **200** | OK |  -  |
 
-<a name="postPing"></a>
+<a id="postPing"></a>
 # **postPing**
 > SomeObj postPing(someObj)
 

diff --git a/samples/client/petstore/java-micronaut-client/docs/apis/AnotherFakeApi.md b/samples/client/petstore/java-micronaut-client/docs/apis/AnotherFakeApi.md
@@ -35,7 +35,7 @@ Note that the class needs to be annotated with one of Micronaut's [scope annotat
 
 More information can be found inside [Inversion of Control guide section](https://docs.micronaut.io/latest/guide/#ioc).
 
-<a name="call123testSpecialTags"></a>
+<a id="call123testSpecialTags"></a>
 # **call123testSpecialTags**
 ```java
 Mono<ModelClient> AnotherFakeApi.call123testSpecialTags(_body)