Skip to content

Commit e7ddde7

Browse files
winridwinrid
committed
improve doc generation - don't try link to internal models, and fixing links missing in some scenarios
the rust doc generator will be the death of me
1 parent 9212fef commit e7ddde7

114 files changed

Lines changed: 600 additions & 107 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/java/org/openapitools/codegen/languages/RustClientCodegen.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,45 @@ public ModelsMap postProcessModels(ModelsMap objs) {
368368
break;
369369
}
370370
}
371+
372+
// Compute documentation type for each property
373+
// This matches the actual generated code type, including HashSet for uniqueItems
374+
for (CodegenProperty cp : cm.vars) {
375+
String docType;
376+
377+
if (cp.datatypeWithEnum != null && !cp.datatypeWithEnum.isEmpty()) {
378+
// Use enum type if available (e.g., Vec<UniqueItemArray> instead of Vec<String>)
379+
docType = cp.datatypeWithEnum;
380+
} else {
381+
// Use regular dataType
382+
docType = cp.dataType;
383+
}
384+
385+
// Apply uniqueItems logic (matching model.mustache lines 139, 161)
386+
// Arrays with uniqueItems=true use HashSet instead of Vec in the generated code
387+
if (Boolean.TRUE.equals(cp.getUniqueItems()) && docType.startsWith("Vec<")) {
388+
docType = docType.replace("Vec<", "HashSet<");
389+
}
390+
391+
cp.vendorExtensions.put("x-doc-type", docType);
392+
393+
// Determine if this type should have a doc link
394+
// Only local models should link, not external types from std lib or crates
395+
boolean shouldLink = false;
396+
if (cp.complexType != null && !cp.complexType.isEmpty()) {
397+
// Check if it's an external type by looking for known prefixes
398+
String[] externalPrefixes = {"std::", "serde_json::", "uuid::", "chrono::", "url::"};
399+
boolean isExternal = false;
400+
for (String prefix : externalPrefixes) {
401+
if (cp.complexType.startsWith(prefix)) {
402+
isExternal = true;
403+
break;
404+
}
405+
}
406+
shouldLink = !isExternal;
407+
}
408+
cp.vendorExtensions.put("x-should-link", shouldLink);
409+
}
371410
}
372411
// process enum in models
373412
return postProcessModelsEnum(objs);

‎modules/openapi-generator/src/main/resources/rust/model_doc.mustache‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
Name | Type | Description | Notes
2424
------------ | ------------- | ------------- | -------------
25-
{{#vars}}**{{{name}}}** | {{^required}}Option<{{/required}}{{#required}}{{#isNullable}}Option<{{/isNullable}}{{/required}}{{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#complexType}}[**{{{dataType}}}**]({{#lambda.pascalcase}}{{{complexType}}}{{/lambda.pascalcase}}.md){{/complexType}}{{^complexType}}**{{{dataType}}}**{{/complexType}}{{/isPrimitiveType}}{{^required}}>{{/required}}{{#required}}{{#isNullable}}>{{/isNullable}}{{/required}} | {{{description}}}{{#isInnerEnum}} (enum: {{#allowableValues}}{{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}){{/isInnerEnum}} | {{^required}}[optional]{{/required}}{{#isReadOnly}}[readonly]{{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
25+
{{#vars}}**{{{name}}}** | {{^required}}Option<{{/required}}{{#required}}{{#isNullable}}Option<{{/isNullable}}{{/required}}{{#vendorExtensions.x-should-link}}[**{{{vendorExtensions.x-doc-type}}}**]({{#lambda.pascalcase}}{{{complexType}}}{{/lambda.pascalcase}}.md){{/vendorExtensions.x-should-link}}{{^vendorExtensions.x-should-link}}**{{{vendorExtensions.x-doc-type}}}**{{/vendorExtensions.x-should-link}}{{^required}}>{{/required}}{{#required}}{{#isNullable}}>{{/isNullable}}{{/required}} | {{{description}}}{{#isInnerEnum}} (enum: {{#allowableValues}}{{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}){{/isInnerEnum}} | {{^required}}[optional]{{/required}}{{#isReadOnly}}[readonly]{{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
2626
{{/vars}}
2727
{{/x-mapped-models}}
2828
{{/vendorExtensions}}
@@ -35,7 +35,7 @@ Name | Type | Description | Notes
3535

3636
Name | Type | Description | Notes
3737
------------ | ------------- | ------------- | -------------
38-
{{#vars}}**{{{name}}}** | {{^required}}Option<{{/required}}{{#required}}{{#isNullable}}Option<{{/isNullable}}{{/required}}{{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#complexType}}[**{{{dataType}}}**]({{#lambda.pascalcase}}{{{complexType}}}{{/lambda.pascalcase}}.md){{/complexType}}{{^complexType}}**{{{dataType}}}**{{/complexType}}{{/isPrimitiveType}}{{^required}}>{{/required}}{{#required}}{{#isNullable}}>{{/isNullable}}{{/required}} | {{{description}}}{{#isInnerEnum}} (enum: {{#allowableValues}}{{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}){{/isInnerEnum}} | {{^required}}[optional]{{/required}}{{#isReadOnly}}[readonly]{{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
38+
{{#vars}}**{{{name}}}** | {{^required}}Option<{{/required}}{{#required}}{{#isNullable}}Option<{{/isNullable}}{{/required}}{{#vendorExtensions.x-should-link}}[**{{{vendorExtensions.x-doc-type}}}**]({{#lambda.pascalcase}}{{{complexType}}}{{/lambda.pascalcase}}.md){{/vendorExtensions.x-should-link}}{{^vendorExtensions.x-should-link}}**{{{vendorExtensions.x-doc-type}}}**{{/vendorExtensions.x-should-link}}{{^required}}>{{/required}}{{#required}}{{#isNullable}}>{{/isNullable}}{{/required}} | {{{description}}}{{#isInnerEnum}} (enum: {{#allowableValues}}{{#values}}{{{.}}}{{^-last}}, {{/-last}}{{/values}}{{/allowableValues}}){{/isInnerEnum}} | {{^required}}[optional]{{/required}}{{#isReadOnly}}[readonly]{{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
3939
{{/vars}}
4040
{{/oneOf.isEmpty}}
4141
{{^oneOf.isEmpty}}

‎samples/client/others/rust/hyper/api-with-ref-param/docs/DefaultApi.md‎

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

1919
Name | Type | Description | Required | Notes
2020
------------- | ------------- | ------------- | ------------- | -------------
21-
**color** | [**Color**](.md) | | [required] |
21+
**color** | [**Color**](Color.md) | | [required] |
2222

2323
### Return type
2424

‎samples/client/others/rust/hyper/emptyObject/docs/EmptyObject.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Name | Type | Description | Notes
66
------------ | ------------- | ------------- | -------------
7-
**empty_object** | Option<[**serde_json::Value**](.md)> | | [optional]
7+
**empty_object** | Option<**serde_json::Value**> | | [optional]
88

99
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
1010

‎samples/client/others/rust/reqwest-regression-16119/docs/Parent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Name | Type | Description | Notes
66
------------ | ------------- | ------------- | -------------
7-
**child** | Option<[**std::collections::HashMap<String, serde_json::Value>**](SerdeJson__Value.md)> | | [optional]
7+
**child** | Option<**std::collections::HashMap<String, serde_json::Value>**> | | [optional]
88

99
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
1010

‎samples/client/others/rust/reqwest/enum-query-params/docs/AggregateResponse.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Name | Type | Description | Notes
66
------------ | ------------- | ------------- | -------------
77
**count** | Option<**i64**> | | [optional]
8-
**data** | Option<[**Vec<std::collections::HashMap<String, serde_json::Value>>**](Std__collections__HashMap.md)> | | [optional]
8+
**data** | Option<**Vec<std::collections::HashMap<String, serde_json::Value>>**> | | [optional]
99

1010
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
1111

‎samples/client/petstore/rust/hyper/petstore/.openapi-generator/FILES‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ docs/Baz.md
1010
docs/Category.md
1111
docs/EnumArrayTesting.md
1212
docs/FakeApi.md
13+
docs/ModelWithInlineEnum.md
14+
docs/ModelWithInlineEnumMetadata.md
1315
docs/NullableArray.md
1416
docs/NumericEnumTesting.md
1517
docs/OptionalTesting.md
@@ -52,6 +54,8 @@ src/models/enum_array_testing.rs
5254
src/models/mod.rs
5355
src/models/model_ref.rs
5456
src/models/model_return.rs
57+
src/models/model_with_inline_enum.rs
58+
src/models/model_with_inline_enum_metadata.rs
5559
src/models/nullable_array.rs
5660
src/models/numeric_enum_testing.rs
5761
src/models/optional_testing.rs

‎samples/client/petstore/rust/hyper/petstore/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ Class | Method | HTTP request | Description
4343
*StoreApi* | [**place_order**](docs/StoreApi.md#place_order) | **Post** /store/order | Place an order for a pet
4444
*TestingApi* | [**tests_all_of_with_one_model_get**](docs/TestingApi.md#tests_all_of_with_one_model_get) | **Get** /tests/allOfWithOneModel | Test for allOf with a single option. (One of the issues in #20500)
4545
*TestingApi* | [**tests_file_response_get**](docs/TestingApi.md#tests_file_response_get) | **Get** /tests/fileResponse | Returns an image file
46+
*TestingApi* | [**tests_inline_enum_boxing_get**](docs/TestingApi.md#tests_inline_enum_boxing_get) | **Get** /tests/inlineEnumBoxing | Get model with inline enums
47+
*TestingApi* | [**tests_inline_enum_boxing_post**](docs/TestingApi.md#tests_inline_enum_boxing_post) | **Post** /tests/inlineEnumBoxing | Test for inline enum fields not being boxed in model constructors
4648
*TestingApi* | [**tests_type_testing_get**](docs/TestingApi.md#tests_type_testing_get) | **Get** /tests/typeTesting | Route to test the TypeTesting schema
4749
*UserApi* | [**create_user**](docs/UserApi.md#create_user) | **Post** /user | Create user
4850
*UserApi* | [**create_users_with_array_input**](docs/UserApi.md#create_users_with_array_input) | **Post** /user/createWithArray | Creates list of users with given input array
@@ -63,6 +65,8 @@ Class | Method | HTTP request | Description
6365
- [Baz](docs/Baz.md)
6466
- [Category](docs/Category.md)
6567
- [EnumArrayTesting](docs/EnumArrayTesting.md)
68+
- [ModelWithInlineEnum](docs/ModelWithInlineEnum.md)
69+
- [ModelWithInlineEnumMetadata](docs/ModelWithInlineEnumMetadata.md)
6670
- [NullableArray](docs/NullableArray.md)
6771
- [NumericEnumTesting](docs/NumericEnumTesting.md)
6872
- [OptionalTesting](docs/OptionalTesting.md)

‎samples/client/petstore/rust/hyper/petstore/docs/AnyTypeTest.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Name | Type | Description | Notes
66
------------ | ------------- | ------------- | -------------
7-
**foo** | Option<[**serde_json::Value**](.md)> | |
7+
**foo** | Option<**serde_json::Value**> | |
88

99
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
1010

‎samples/client/petstore/rust/hyper/petstore/docs/ArrayItemRefTest.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Name | Type | Description | Notes
66
------------ | ------------- | ------------- | -------------
77
**list_with_array_ref** | [**Vec<Vec<String>>**](Vec.md) | |
8-
**list_with_object_ref** | [**Vec<std::collections::HashMap<String, serde_json::Value>>**](std::collections::HashMap.md) | |
8+
**list_with_object_ref** | **Vec<std::collections::HashMap<String, serde_json::Value>>** | |
99

1010
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
1111

0 commit comments

Comments
 (0)