Skip to content

Commit b4b8c28

Browse files
Luis Alejandro Herrera Leónwing328
Luis Alejandro Herrera León
authored and
wing328
committed
[rust-server] Added client documentation to rust-server (#2159)
* Added client documentation to rust-server * Removed comments * Removed go auth example
1 parent 594af33 commit b4b8c28

Some content is hidden

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

53 files changed

+2030
-3
lines changed

‎modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/RustServerCodegen.java

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ public class RustServerCodegen extends DefaultCodegen implements CodegenConfig {
5454
protected int serverPort = 8080;
5555
protected String projectName = "openapi-server";
5656
protected String apiPath = "rust-server";
57+
protected String apiDocPath = "docs/";
58+
protected String modelDocPath = "docs/";
5759
protected String packageName;
5860
protected String packageVersion;
5961
protected String externCrateName;
@@ -83,6 +85,9 @@ public RustServerCodegen() {
8385
*/
8486
apiTemplateFiles.clear();
8587

88+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
89+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
90+
8691
/*
8792
* Template Location. This is the location which templates will be read from. The generator
8893
* will use the resource stream to attempt to read the templates.
@@ -127,7 +132,8 @@ public RustServerCodegen() {
127132
"usize",
128133
"f32",
129134
"f64",
130-
"str")
135+
"str",
136+
"String")
131137
);
132138

133139
instantiationTypes.clear();
@@ -209,6 +215,9 @@ public void processOpts() {
209215
setPackageVersion((String) additionalProperties.get(CodegenConstants.PACKAGE_VERSION));
210216
}
211217

218+
additionalProperties.put("apiDocPath", apiDocPath);
219+
additionalProperties.put("modelDocPath", modelDocPath);
220+
212221
additionalProperties.put(CodegenConstants.PACKAGE_NAME, packageName);
213222
additionalProperties.put(CodegenConstants.PACKAGE_VERSION, packageVersion);
214223
additionalProperties.put("externCrateName", externCrateName);
@@ -439,6 +448,26 @@ public String toApiFilename(String name) {
439448
return underscore(name);
440449
}
441450

451+
@Override
452+
public String apiDocFileFolder() {
453+
return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
454+
}
455+
456+
@Override
457+
public String modelDocFileFolder() {
458+
return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
459+
}
460+
461+
@Override
462+
public String toModelDocFilename(String name) {
463+
return toModelName(name);
464+
}
465+
466+
@Override
467+
public String toApiDocFilename(String name) {
468+
return toApiName(name) + "_api";
469+
}
470+
442471
@Override
443472
public String escapeQuotationMark(String input) {
444473
// remove " to avoid code injection
@@ -765,7 +794,6 @@ public CodegenParameter fromParameter(Parameter param, Set<String> imports) {
765794

766795
String name = "models::" + getTypeDeclaration(parameter.dataType);
767796
parameter.dataType = name;
768-
parameter.baseType = name;
769797
}
770798

771799
return parameter;
@@ -783,7 +811,6 @@ public void postProcessParameter(CodegenParameter parameter) {
783811

784812
String name = "models::" + getTypeDeclaration(parameter.dataType);
785813
parameter.dataType = name;
786-
parameter.baseType = name;
787814
}
788815
}
789816

@@ -928,6 +955,9 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
928955
} else {
929956
property.dataType = camelize(property.dataType, false);
930957
}
958+
property.isPrimitiveType = property.isContainer && languageSpecificPrimitives.contains(typeMapping.get(property.complexType));
959+
} else {
960+
property.isPrimitiveType = true;
931961
}
932962

933963
if ("integer".equals(property.baseType)) {

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,3 +110,60 @@ Now replace the implementations in `src/server.rs` with your own code as require
110110

111111
Later, if the API changes, you can copy new sections from the autogenerated API stub into your implementation.
112112
Alternatively, implement the now-missing methods based on the compiler's error messages.
113+
114+
## Documentation for API Endpoints
115+
116+
All URIs are relative to *{{{basePath}}}*
117+
118+
Method | HTTP request | Description
119+
------------- | ------------- | -------------
120+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}[**{{{operationIdOriginal}}}**]({{{apiDocPath}}}{{classname}}_api.md#{{{operationIdOriginal}}}) | **{{{httpMethod}}}** {{{path}}} | {{#summary}}{{{summary}}}{{/summary}}
121+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
122+
123+
## Documentation For Models
124+
125+
{{#models}}{{#model}} - [{{{classname}}}]({{{modelDocPath}}}{{{classname}}}.md)
126+
{{/model}}{{/models}}
127+
128+
## Documentation For Authorization
129+
{{^authMethods}} Endpoints do not require authorization.
130+
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
131+
{{#authMethods}}
132+
## {{{name}}}
133+
{{#isApiKey}}- **Type**: API key
134+
135+
Example
136+
```
137+
{{! TODO: Add API Key example }}
138+
```
139+
{{/isApiKey}}
140+
{{#isBasic}}- **Type**: HTTP basic authentication
141+
142+
Example
143+
```
144+
{{! TODO: Add HTTP basic authentication }}
145+
```
146+
{{/isBasic}}
147+
{{#isOAuth}}- **Type**: OAuth
148+
- **Flow**: {{{flow}}}
149+
- **Authorization URL**: {{{authorizationUrl}}}
150+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
151+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
152+
{{/scopes}}
153+
154+
Example
155+
```
156+
{{! TODO: OAuth example }}
157+
```
158+
159+
Or via OAuth2 module to automatically refresh tokens and perform user authentication.
160+
```
161+
{{! TODO: OAuth example }}
162+
```
163+
{{/isOAuth}}
164+
{{/authMethods}}
165+
166+
## Author
167+
168+
{{#apiInfo}}{{#apis}}{{^hasMore}}{{{infoEmail}}}
169+
{{/hasMore}}{{/apis}}{{/apiInfo}}

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# {{{invokerPackage}}}{{{classname}}}_api{{#description}}
2+
{{{description}}}{{/description}}
3+
4+
All URIs are relative to *{{{basePath}}}*
5+
6+
Method | HTTP request | Description
7+
------------- | ------------- | -------------
8+
{{#operations}}{{#operation}}**{{{operationIdOriginal}}}**]({{classname}}_api.md#{{{operationIdOriginal}}}) | **{{{httpMethod}}}** {{{path}}} | {{#summary}}{{{summary}}}{{/summary}}
9+
{{/operation}}{{/operations}}
10+
11+
{{#operations}}
12+
{{#operation}}
13+
# **{{{operationIdOriginal}}}**
14+
> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationIdOriginal}}}({{#authMethods}}ctx, {{/authMethods}}{{#allParams}}{{#required}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/required}}{{/allParams}}{{#hasOptionalParams}}optional{{/hasOptionalParams}})
15+
{{{summary}}}{{#notes}}
16+
17+
{{{notes}}}{{/notes}}
18+
19+
### Required Parameters
20+
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
21+
Name | Type | Description | Notes
22+
------------- | ------------- | ------------- | -------------{{#authMethods}}
23+
**ctx** | **context.Context** | context containing the authentication | nil if no authentication{{/authMethods}}{{/-last}}{{/allParams}}{{#allParams}}{{#required}}
24+
**{{{paramName}}}** | {{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{{baseType}}}**]({{{baseType}}}.md){{/isPrimitiveType}}| {{{description}}} | {{#defaultValue}}[default to {{{defaultValue}}}]{{/defaultValue}}{{/required}}{{/allParams}}{{#hasOptionalParams}}
25+
**optional** | **map[string]interface{}** | optional parameters | nil if no parameters
26+
27+
### Optional Parameters
28+
Optional parameters are passed through a map[string]interface{}.
29+
{{#allParams}}{{#-last}}
30+
Name | Type | Description | Notes
31+
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}{{#allParams}}
32+
**{{{paramName}}}** | {{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{{baseType}}}**]({{{baseType}}}.md){{/isPrimitiveType}}| {{{description}}} | {{#defaultValue}}[default to {{{defaultValue}}}]{{/defaultValue}}{{/allParams}}{{/hasOptionalParams}}
33+
34+
### Return type
35+
36+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{{returnBaseType}}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}} (empty response body){{/returnType}}
37+
38+
### Authorization
39+
40+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
41+
42+
### HTTP request headers
43+
44+
- **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
45+
- **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
46+
47+
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
48+
49+
{{/operation}}
50+
{{/operations}}

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{#models}}{{#model}}# {{{classname}}}
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
{{#vars}}**{{{name}}}** | {{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{^isContainer}}{{^isDateTime}}*{{/isDateTime}}{{/isContainer}}{{{dataType}}}**]({{{complexType}}}.md){{/isPrimitiveType}} | {{{description}}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
7+
{{/vars}}
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+
{{/model}}{{/models}}

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/README.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,3 +133,123 @@ Now replace the implementations in `src/server.rs` with your own code as require
133133

134134
Later, if the API changes, you can copy new sections from the autogenerated API stub into your implementation.
135135
Alternatively, implement the now-missing methods based on the compiler's error messages.
136+
137+
## Documentation for API Endpoints
138+
139+
All URIs are relative to *http://petstore.swagger.io:80/v2*
140+
141+
Method | HTTP request | Description
142+
------------- | ------------- | -------------
143+
[**test_special_tags**](docs/another_fake_api.md#test_special_tags) | **PATCH** /another-fake/dummy | To test special tags
144+
[**fakeOuterBooleanSerialize**](docs/fake_api.md#fakeOuterBooleanSerialize) | **POST** /fake/outer/boolean |
145+
[**fakeOuterCompositeSerialize**](docs/fake_api.md#fakeOuterCompositeSerialize) | **POST** /fake/outer/composite |
146+
[**fakeOuterNumberSerialize**](docs/fake_api.md#fakeOuterNumberSerialize) | **POST** /fake/outer/number |
147+
[**fakeOuterStringSerialize**](docs/fake_api.md#fakeOuterStringSerialize) | **POST** /fake/outer/string |
148+
[**testBodyWithQueryParams**](docs/fake_api.md#testBodyWithQueryParams) | **PUT** /fake/body-with-query-params |
149+
[**testClientModel**](docs/fake_api.md#testClientModel) | **PATCH** /fake | To test \"client\" model
150+
[**testEndpointParameters**](docs/fake_api.md#testEndpointParameters) | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트
151+
[**testEnumParameters**](docs/fake_api.md#testEnumParameters) | **GET** /fake | To test enum parameters
152+
[**testInlineAdditionalProperties**](docs/fake_api.md#testInlineAdditionalProperties) | **POST** /fake/inline-additionalProperties | test inline additionalProperties
153+
[**testJsonFormData**](docs/fake_api.md#testJsonFormData) | **GET** /fake/jsonFormData | test json serialization of form data
154+
[**testClassname**](docs/fake_classname_tags123_api.md#testClassname) | **PATCH** /fake_classname_test | To test class name in snake case
155+
[**addPet**](docs/pet_api.md#addPet) | **POST** /pet | Add a new pet to the store
156+
[**deletePet**](docs/pet_api.md#deletePet) | **DELETE** /pet/{petId} | Deletes a pet
157+
[**findPetsByStatus**](docs/pet_api.md#findPetsByStatus) | **GET** /pet/findByStatus | Finds Pets by status
158+
[**findPetsByTags**](docs/pet_api.md#findPetsByTags) | **GET** /pet/findByTags | Finds Pets by tags
159+
[**getPetById**](docs/pet_api.md#getPetById) | **GET** /pet/{petId} | Find pet by ID
160+
[**updatePet**](docs/pet_api.md#updatePet) | **PUT** /pet | Update an existing pet
161+
[**updatePetWithForm**](docs/pet_api.md#updatePetWithForm) | **POST** /pet/{petId} | Updates a pet in the store with form data
162+
[**uploadFile**](docs/pet_api.md#uploadFile) | **POST** /pet/{petId}/uploadImage | uploads an image
163+
[**deleteOrder**](docs/store_api.md#deleteOrder) | **DELETE** /store/order/{order_id} | Delete purchase order by ID
164+
[**getInventory**](docs/store_api.md#getInventory) | **GET** /store/inventory | Returns pet inventories by status
165+
[**getOrderById**](docs/store_api.md#getOrderById) | **GET** /store/order/{order_id} | Find purchase order by ID
166+
[**placeOrder**](docs/store_api.md#placeOrder) | **POST** /store/order | Place an order for a pet
167+
[**createUser**](docs/user_api.md#createUser) | **POST** /user | Create user
168+
[**createUsersWithArrayInput**](docs/user_api.md#createUsersWithArrayInput) | **POST** /user/createWithArray | Creates list of users with given input array
169+
[**createUsersWithListInput**](docs/user_api.md#createUsersWithListInput) | **POST** /user/createWithList | Creates list of users with given input array
170+
[**deleteUser**](docs/user_api.md#deleteUser) | **DELETE** /user/{username} | Delete user
171+
[**getUserByName**](docs/user_api.md#getUserByName) | **GET** /user/{username} | Get user by user name
172+
[**loginUser**](docs/user_api.md#loginUser) | **GET** /user/login | Logs user into the system
173+
[**logoutUser**](docs/user_api.md#logoutUser) | **GET** /user/logout | Logs out current logged in user session
174+
[**updateUser**](docs/user_api.md#updateUser) | **PUT** /user/{username} | Updated user
175+
176+
177+
## Documentation For Models
178+
179+
- [AdditionalPropertiesClass](docs/AdditionalPropertiesClass.md)
180+
- [Animal](docs/Animal.md)
181+
- [ApiResponse](docs/ApiResponse.md)
182+
- [ArrayOfArrayOfNumberOnly](docs/ArrayOfArrayOfNumberOnly.md)
183+
- [ArrayOfNumberOnly](docs/ArrayOfNumberOnly.md)
184+
- [ArrayTest](docs/ArrayTest.md)
185+
- [Capitalization](docs/Capitalization.md)
186+
- [Cat](docs/Cat.md)
187+
- [Category](docs/Category.md)
188+
- [ClassModel](docs/ClassModel.md)
189+
- [Client](docs/Client.md)
190+
- [Dog](docs/Dog.md)
191+
- [EnumArrays](docs/EnumArrays.md)
192+
- [EnumClass](docs/EnumClass.md)
193+
- [EnumTest](docs/EnumTest.md)
194+
- [FormatTest](docs/FormatTest.md)
195+
- [HasOnlyReadOnly](docs/HasOnlyReadOnly.md)
196+
- [List](docs/List.md)
197+
- [MapTest](docs/MapTest.md)
198+
- [MixedPropertiesAndAdditionalPropertiesClass](docs/MixedPropertiesAndAdditionalPropertiesClass.md)
199+
- [Model200Response](docs/Model200Response.md)
200+
- [ModelReturn](docs/ModelReturn.md)
201+
- [Name](docs/Name.md)
202+
- [NumberOnly](docs/NumberOnly.md)
203+
- [Order](docs/Order.md)
204+
- [OuterBoolean](docs/OuterBoolean.md)
205+
- [OuterComposite](docs/OuterComposite.md)
206+
- [OuterEnum](docs/OuterEnum.md)
207+
- [OuterNumber](docs/OuterNumber.md)
208+
- [OuterString](docs/OuterString.md)
209+
- [Pet](docs/Pet.md)
210+
- [ReadOnlyFirst](docs/ReadOnlyFirst.md)
211+
- [SpecialModelName](docs/SpecialModelName.md)
212+
- [Tag](docs/Tag.md)
213+
- [User](docs/User.md)
214+
215+
216+
## Documentation For Authorization
217+
218+
## api_key
219+
- **Type**: API key
220+
221+
Example
222+
```
223+
```
224+
## api_key_query
225+
- **Type**: API key
226+
227+
Example
228+
```
229+
```
230+
## http_basic_test
231+
- **Type**: HTTP basic authentication
232+
233+
Example
234+
```
235+
```
236+
## petstore_auth
237+
- **Type**: OAuth
238+
- **Flow**: implicit
239+
- **Authorization URL**: http://petstore.swagger.io/api/oauth/dialog
240+
- **Scopes**:
241+
- **write:pets**: modify pets in your account
242+
- **read:pets**: read your pets
243+
244+
Example
245+
```
246+
```
247+
248+
Or via OAuth2 module to automatically refresh tokens and perform user authentication.
249+
```
250+
```
251+
252+
## Author
253+
254+
255+

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/docs/AdditionalPropertiesClass.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# AdditionalPropertiesClass
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**map_property** | **HashMap<String, String>** | | [optional] [default to None]
7+
**map_of_map_property** | [**HashMap<String, HashMap<String, String>>**](map.md) | | [optional] [default to None]
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/docs/Animal.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Animal
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**class_name** | **String** | |
7+
**color** | **String** | | [optional] [default to Some("red".to_string())]
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/docs/ApiResponse.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# ApiResponse
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**code** | **i32** | | [optional] [default to None]
7+
**_type** | **String** | | [optional] [default to None]
8+
**message** | **String** | | [optional] [default to None]
9+
10+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
11+
12+

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/docs/ArrayOfArrayOfNumberOnly.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# ArrayOfArrayOfNumberOnly
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**array_array_number** | [**Vec<Vec<f64>>**](array.md) | | [optional] [default to None]
7+
8+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
9+
10+

‎samples/server/petstore/rust-server/output/petstore-with-fake-endpoints-models-for-testing/docs/ArrayOfNumberOnly.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# ArrayOfNumberOnly
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**array_number** | **Vec<f64>** | | [optional] [default to None]
7+
8+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
9+
10+

0 commit comments

Comments
 (0)