Skip to content

Commit a603ccb

Browse files
wing328wing328
authored
[Dart] add auto-generated documentation (#4291)
* new files for dart client * update doc for dart * update api and model doc for dart * update dart petstore sample * update dart doc * update dart petstore sample * update dart petstore sample * update dart client installation instruction
1 parent b733334 commit a603ccb

File tree

15 files changed

+1445
-1
lines changed

15 files changed

+1445
-1
lines changed

‎bin/dart-petstore.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ fi
2727
# if you've executed sbt assembly previously it will use that instead.
2828
export JAVA_OPTS="${JAVA_OPTS} -XX:MaxPermSize=256M -Xmx1024M -DloggerPath=conf/log4j.properties"
2929

30-
ags="$@ generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml -l dart -o samples/client/petstore/dart/swagger"
30+
ags="$@ generate -t modules/swagger-codegen/src/main/resources/dart -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml -l dart -o samples/client/petstore/dart/swagger"
3131

3232
# then options to generate the library for vm would be:
3333
#ags="$@ generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml -l dart -o samples/client/petstore/dart/swagger_vm -DbrowserClient=false -DpubName=swagger_vm"

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/DartClientCodegen.java

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
2525
protected String pubVersion = "1.0.0";
2626
protected String pubDescription = "Swagger API client";
2727
protected String sourceFolder = "";
28+
protected String apiDocPath = "docs/";
29+
protected String modelDocPath = "docs/";
2830

2931
public DartClientCodegen() {
3032
super();
@@ -39,6 +41,8 @@ public DartClientCodegen() {
3941
embeddedTemplateDir = templateDir = "dart";
4042
apiPackage = "lib.api";
4143
modelPackage = "lib.model";
44+
modelDocTemplateFiles.put("object_doc.mustache", ".md");
45+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
4246

4347
setReservedWordsLowerCase(
4448
Arrays.asList(
@@ -145,6 +149,10 @@ public void processOpts() {
145149
this.setSourceFolder((String) additionalProperties.get(CodegenConstants.SOURCE_FOLDER));
146150
}
147151

152+
// make api and model doc path available in mustache template
153+
additionalProperties.put("apiDocPath", apiDocPath);
154+
additionalProperties.put("modelDocPath", modelDocPath);
155+
148156
final String libFolder = sourceFolder + File.separator + "lib";
149157
supportingFiles.add(new SupportingFile("pubspec.mustache", "", "pubspec.yaml"));
150158
supportingFiles.add(new SupportingFile("analysis_options.mustache", "", ".analysis_options"));
@@ -160,6 +168,7 @@ public void processOpts() {
160168
supportingFiles.add(new SupportingFile("auth/oauth.mustache", authFolder, "oauth.dart"));
161169
supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
162170
supportingFiles.add(new SupportingFile("gitignore.mustache", "", ".gitignore"));
171+
supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
163172

164173
}
165174

@@ -179,6 +188,16 @@ public String modelFileFolder() {
179188
return outputFolder + "/" + sourceFolder + "/" + modelPackage().replace('.', File.separatorChar);
180189
}
181190

191+
@Override
192+
public String apiDocFileFolder() {
193+
return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
194+
}
195+
196+
@Override
197+
public String modelDocFileFolder() {
198+
return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
199+
}
200+
182201
@Override
183202
public String toVarName(String name) {
184203
// replace - with _ e.g. created-at => created_at

‎modules/swagger-codegen/src/main/resources/dart/README.mustache

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# {{pubName}}
2+
{{#appDescription}}
3+
{{{appDescription}}}
4+
{{/appDescription}}
5+
6+
This Dart package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
7+
8+
- API version: {{appVersion}}
9+
{{#artifactVersion}}
10+
- Package version: {{artifactVersion}}
11+
{{/artifactVersion}}
12+
{{^hideGenerationTimestamp}}
13+
- Build date: {{generatedDate}}
14+
{{/hideGenerationTimestamp}}
15+
- Build package: {{generatorClass}}
16+
{{#infoUrl}}
17+
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
18+
{{/infoUrl}}
19+
20+
## Requirements
21+
22+
Dart 1.20.0 and later
23+
24+
## Installation & Usage
25+
26+
### Github
27+
If this Dart package is published to Github, please include the following in pubspec.yaml
28+
```
29+
name: {{pubName}}
30+
version: {{pubVersion}}
31+
description: {{pubDescription}}
32+
dependencies:
33+
{{pubName}}:
34+
git: https://github.com/{{gitUserId}}/{{gitRepoId}}.git
35+
version: 'any'
36+
```
37+
38+
### Local
39+
To use the package in your local drive, please include the following in pubspec.yaml
40+
```
41+
dependencies:
42+
{{pubName}}:
43+
path: /path/to/{{pubName}}
44+
```
45+
46+
## Tests
47+
48+
TODO
49+
50+
## Getting Started
51+
52+
Please follow the [installation procedure](#installation--usage) and then run the following:
53+
54+
```dart
55+
import 'package:{{pubName}}/api.dart';
56+
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
57+
{{#hasAuthMethods}}
58+
{{#authMethods}}
59+
{{#isBasic}}
60+
// TODO Configure HTTP basic authorization: {{{name}}}
61+
//{{pubName}}.api.Configuration.username = 'YOUR_USERNAME';
62+
//{{pubName}}.api.Configuration.password = 'YOUR_PASSWORD';
63+
{{/isBasic}}
64+
{{#isApiKey}}
65+
// TODO Configure API key authorization: {{{name}}}
66+
//{{pubName}}.api.Configuration.apiKey{'{{{keyParamName}}}'} = 'YOUR_API_KEY';
67+
// uncomment below to setup prefix (e.g. Bearer) for API key, if needed
68+
//{{pubName}}.api.Configuration.apiKeyPrefix{'{{{keyParamName}}}'} = "Bearer";
69+
{{/isApiKey}}
70+
{{#isOAuth}}
71+
// TODO Configure OAuth2 access token for authorization: {{{name}}}
72+
//{{pubName}}.api.Configuration.accessToken = 'YOUR_ACCESS_TOKEN';
73+
{{/isOAuth}}
74+
{{/authMethods}}
75+
{{/hasAuthMethods}}
76+
77+
var api_instance = new {{classname}}();
78+
{{#allParams}}
79+
var {{paramName}} = {{#isListContainer}}[{{/isListContainer}}{{#isBodyParam}}new {{dataType}}(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}]{{/isListContainer}}; // {{{dataType}}} | {{{description}}}
80+
{{/allParams}}
81+
82+
try {
83+
{{#returnType}}var result = {{/returnType}}api_instance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});
84+
{{#returnType}}
85+
print(result);
86+
{{/returnType}}
87+
} catch (e) {
88+
print("Exception when calling {{classname}}->{{operationId}}: $e\n");
89+
}
90+
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
91+
```
92+
93+
## Documentation for API Endpoints
94+
95+
All URIs are relative to *{{basePath}}*
96+
97+
Class | Method | HTTP request | Description
98+
------------ | ------------- | ------------- | -------------
99+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}/{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
100+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
101+
102+
## Documentation For Models
103+
104+
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}/{{{classname}}}.md)
105+
{{/model}}{{/models}}
106+
107+
## Documentation For Authorization
108+
109+
{{^authMethods}} All endpoints do not require authorization.
110+
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
111+
{{#authMethods}}## {{{name}}}
112+
113+
{{#isApiKey}}- **Type**: API key
114+
- **API key parameter name**: {{{keyParamName}}}
115+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
116+
{{/isApiKey}}
117+
{{#isBasic}}- **Type**: HTTP basic authentication
118+
{{/isBasic}}
119+
{{#isOAuth}}- **Type**: OAuth
120+
- **Flow**: {{{flow}}}
121+
- **Authorization URL**: {{{authorizationUrl}}}
122+
- **Scopes**: {{^scopes}}N/A{{/scopes}}
123+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
124+
{{/scopes}}
125+
{{/isOAuth}}
126+
127+
{{/authMethods}}
128+
129+
## Author
130+
131+
{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}
132+
{{/hasMore}}{{/apis}}{{/apiInfo}}
133+

‎modules/swagger-codegen/src/main/resources/dart/api_doc.mustache

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# {{pubName}}.api.{{classname}}{{#description}}
2+
{{description}}{{/description}}
3+
4+
## Load the API package
5+
```dart
6+
import 'package:{{pubName}}/api.dart';
7+
```
8+
9+
All URIs are relative to *{{basePath}}*
10+
11+
Method | HTTP request | Description
12+
------------- | ------------- | -------------
13+
{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
14+
{{/operation}}{{/operations}}
15+
16+
{{#operations}}
17+
{{#operation}}
18+
# **{{{operationId}}}**
19+
> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
20+
21+
{{{summary}}}{{#notes}}
22+
23+
{{{notes}}}{{/notes}}
24+
25+
### Example
26+
```dart
27+
import '{{pubName}}.api';
28+
import '{{pubName}}.model';
29+
{{#hasAuthMethods}}
30+
{{#authMethods}}
31+
{{#isBasic}}
32+
// TODO Configure HTTP basic authorization: {{{name}}}
33+
//{{pubName}}.api.Configuration.username = 'YOUR_USERNAME';
34+
//{{pubName}}.api.Configuration.password = 'YOUR_PASSWORD';
35+
{{/isBasic}}
36+
{{#isApiKey}}
37+
// TODO Configure API key authorization: {{{name}}}
38+
//{{pubName}}.api.Configuration.apiKey{'{{{keyParamName}}}'} = 'YOUR_API_KEY';
39+
// uncomment below to setup prefix (e.g. Bearer) for API key, if needed
40+
//{{pubName}}.api.Configuration.apiKeyPrefix{'{{{keyParamName}}}'} = "Bearer";
41+
{{/isApiKey}}
42+
{{#isOAuth}}
43+
// TODO Configure OAuth2 access token for authorization: {{{name}}}
44+
//{{pubName}}.api.Configuration.accessToken = 'YOUR_ACCESS_TOKEN';
45+
{{/isOAuth}}
46+
{{/authMethods}}
47+
{{/hasAuthMethods}}
48+
49+
var api_instance = new {{classname}}();
50+
{{#allParams}}
51+
var {{paramName}} = {{#isListContainer}}[{{/isListContainer}}{{#isBodyParam}}new {{dataType}}(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}]{{/isListContainer}}; // {{{dataType}}} | {{{description}}}
52+
{{/allParams}}
53+
54+
try {
55+
{{#returnType}}var result = {{/returnType}}api_instance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});
56+
{{#returnType}}
57+
print(result);
58+
{{/returnType}}
59+
} catch (e) {
60+
print("Exception when calling {{classname}}->{{operationId}}: $e\n");
61+
}
62+
```
63+
64+
### Parameters
65+
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
66+
Name | Type | Description | Notes
67+
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
68+
{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
69+
{{/allParams}}
70+
71+
### Return type
72+
73+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
74+
75+
### Authorization
76+
77+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
78+
79+
### HTTP request headers
80+
81+
- **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
82+
- **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
83+
84+
[[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)
85+
86+
{{/operation}}
87+
{{/operations}}

‎modules/swagger-codegen/src/main/resources/dart/object_doc.mustache

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{{#models}}{{#model}}# {{pubName}}.model.{{classname}}
2+
3+
## Load the model package
4+
```dart
5+
import 'package:{{pubName}}/api.dart';
6+
```
7+
8+
## Properties
9+
Name | Type | Description | Notes
10+
------------ | ------------- | ------------- | -------------
11+
{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
12+
{{/vars}}
13+
14+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
15+
16+
{{/model}}{{/models}}

0 commit comments

Comments
 (0)