[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
2016-11-30 17:41:55 +08:00
parent b733334eee
commit a603ccb595
15 changed files with 1445 additions and 1 deletions
--- a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/DartClientCodegen.java
+++ b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/DartClientCodegen.java
@@ -25,6 +25,8 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
    protected String pubVersion = "1.0.0";
    protected String pubDescription = "Swagger API client";
    protected String sourceFolder = "";
+    protected String apiDocPath = "docs/";
+    protected String modelDocPath = "docs/";

    public DartClientCodegen() {
        super();
@@ -39,6 +41,8 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
        embeddedTemplateDir = templateDir = "dart";
        apiPackage = "lib.api";
        modelPackage = "lib.model";
+        modelDocTemplateFiles.put("object_doc.mustache", ".md");
+        apiDocTemplateFiles.put("api_doc.mustache", ".md");

        setReservedWordsLowerCase(
                Arrays.asList(
@@ -145,6 +149,10 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
            this.setSourceFolder((String) additionalProperties.get(CodegenConstants.SOURCE_FOLDER));
        }

+        // make api and model doc path available in mustache template
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
+
        final String libFolder = sourceFolder + File.separator + "lib";
        supportingFiles.add(new SupportingFile("pubspec.mustache", "", "pubspec.yaml"));
        supportingFiles.add(new SupportingFile("analysis_options.mustache", "", ".analysis_options"));
@@ -160,6 +168,7 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
        supportingFiles.add(new SupportingFile("auth/oauth.mustache", authFolder, "oauth.dart"));
        supportingFiles.add(new SupportingFile("git_push.sh.mustache", "", "git_push.sh"));
        supportingFiles.add(new SupportingFile("gitignore.mustache", "", ".gitignore"));
+        supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));

    }

@@ -179,6 +188,16 @@ public class DartClientCodegen extends DefaultCodegen implements CodegenConfig {
        return outputFolder + "/" + sourceFolder + "/" + modelPackage().replace('.', File.separatorChar);
    }

+    @Override
+    public String apiDocFileFolder() {
+        return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
+    }
+
+    @Override
+    public String modelDocFileFolder() {
+        return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
+    }
+
    @Override
    public String toVarName(String name) {
        // replace - with _ e.g. created-at => created_at
--- a/modules/swagger-codegen/src/main/resources/dart/README.mustache
+++ b/modules/swagger-codegen/src/main/resources/dart/README.mustache
@@ -0,0 +1,133 @@
+# {{pubName}}
+{{#appDescription}}
+{{{appDescription}}}
+{{/appDescription}}
+
+This Dart package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
+
+- API version: {{appVersion}}
+{{#artifactVersion}}
+- Package version: {{artifactVersion}}
+{{/artifactVersion}}
+{{^hideGenerationTimestamp}}
+- Build date: {{generatedDate}}
+{{/hideGenerationTimestamp}}
+- Build package: {{generatorClass}}
+{{#infoUrl}}
+For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+## Requirements
+
+Dart 1.20.0 and later
+
+## Installation & Usage
+
+### Github
+If this Dart package is published to Github, please include the following in pubspec.yaml
+```
+name: {{pubName}}
+version: {{pubVersion}}
+description: {{pubDescription}}
+dependencies:
+  {{pubName}}:
+    git: https://github.com/{{gitUserId}}/{{gitRepoId}}.git
+      version: 'any'
+```
+
+### Local
+To use the package in your local drive, please include the following in pubspec.yaml
+```
+dependencies:
+  {{pubName}}:
+    path: /path/to/{{pubName}}
+```
+
+## Tests
+
+TODO
+
+## Getting Started
+
+Please follow the [installation procedure](#installation--usage) and then run the following:
+
+```dart
+import 'package:{{pubName}}/api.dart';
+{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
+{{#hasAuthMethods}}
+{{#authMethods}}
+{{#isBasic}}
+// TODO Configure HTTP basic authorization: {{{name}}}
+//{{pubName}}.api.Configuration.username = 'YOUR_USERNAME';
+//{{pubName}}.api.Configuration.password = 'YOUR_PASSWORD';
+{{/isBasic}}
+{{#isApiKey}}
+// TODO Configure API key authorization: {{{name}}}
+//{{pubName}}.api.Configuration.apiKey{'{{{keyParamName}}}'} = 'YOUR_API_KEY';
+// uncomment below to setup prefix (e.g. Bearer) for API key, if needed
+//{{pubName}}.api.Configuration.apiKeyPrefix{'{{{keyParamName}}}'} = "Bearer";
+{{/isApiKey}}
+{{#isOAuth}}
+// TODO Configure OAuth2 access token for authorization: {{{name}}}
+//{{pubName}}.api.Configuration.accessToken = 'YOUR_ACCESS_TOKEN';
+{{/isOAuth}}
+{{/authMethods}}
+{{/hasAuthMethods}}
+
+var api_instance = new {{classname}}();
+{{#allParams}}
+var {{paramName}} = {{#isListContainer}}[{{/isListContainer}}{{#isBodyParam}}new {{dataType}}(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}]{{/isListContainer}}; // {{{dataType}}} | {{{description}}}
+{{/allParams}}
+
+try {
+    {{#returnType}}var result = {{/returnType}}api_instance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});
+    {{#returnType}}
+    print(result);
+    {{/returnType}}
+} catch (e) {
+    print("Exception when calling {{classname}}->{{operationId}}: $e\n");
+}
+{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
+```
+
+## Documentation for API Endpoints
+
+All URIs are relative to *{{basePath}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}/{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+
+## Documentation For Models
+
+{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}/{{{classname}}}.md)
+{{/model}}{{/models}}
+
+## Documentation For Authorization
+
+{{^authMethods}} All endpoints do not require authorization.
+{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
+{{#authMethods}}## {{{name}}}
+
+{{#isApiKey}}- **Type**: API key
+- **API key parameter name**: {{{keyParamName}}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasic}}- **Type**: HTTP basic authentication
+{{/isBasic}}
+{{#isOAuth}}- **Type**: OAuth
+- **Flow**: {{{flow}}}
+- **Authorization URL**: {{{authorizationUrl}}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}} - **{{{scope}}}**: {{{description}}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}
+
+## Author
+
+{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}
+{{/hasMore}}{{/apis}}{{/apiInfo}}
+
--- a/modules/swagger-codegen/src/main/resources/dart/api_doc.mustache
+++ b/modules/swagger-codegen/src/main/resources/dart/api_doc.mustache
@@ -0,0 +1,87 @@
+# {{pubName}}.api.{{classname}}{{#description}}
+{{description}}{{/description}}
+
+## Load the API package
+```dart
+import 'package:{{pubName}}/api.dart';
+```
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+# **{{{operationId}}}**
+> {{#returnType}}{{{returnType}}} {{/returnType}}{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
+
+{{{summary}}}{{#notes}}
+
+{{{notes}}}{{/notes}}
+
+### Example 
+```dart
+import '{{pubName}}.api';
+import '{{pubName}}.model';
+{{#hasAuthMethods}}
+{{#authMethods}}
+{{#isBasic}}
+// TODO Configure HTTP basic authorization: {{{name}}}
+//{{pubName}}.api.Configuration.username = 'YOUR_USERNAME';
+//{{pubName}}.api.Configuration.password = 'YOUR_PASSWORD';
+{{/isBasic}}
+{{#isApiKey}}
+// TODO Configure API key authorization: {{{name}}}
+//{{pubName}}.api.Configuration.apiKey{'{{{keyParamName}}}'} = 'YOUR_API_KEY';
+// uncomment below to setup prefix (e.g. Bearer) for API key, if needed
+//{{pubName}}.api.Configuration.apiKeyPrefix{'{{{keyParamName}}}'} = "Bearer";
+{{/isApiKey}}
+{{#isOAuth}}
+// TODO Configure OAuth2 access token for authorization: {{{name}}}
+//{{pubName}}.api.Configuration.accessToken = 'YOUR_ACCESS_TOKEN';
+{{/isOAuth}}
+{{/authMethods}}
+{{/hasAuthMethods}}
+
+var api_instance = new {{classname}}();
+{{#allParams}}
+var {{paramName}} = {{#isListContainer}}[{{/isListContainer}}{{#isBodyParam}}new {{dataType}}(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}]{{/isListContainer}}; // {{{dataType}}} | {{{description}}}
+{{/allParams}}
+
+try { 
+    {{#returnType}}var result = {{/returnType}}api_instance.{{{operationId}}}({{#allParams}}{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});
+    {{#returnType}}
+    print(result);
+    {{/returnType}}
+} catch (e) {
+    print("Exception when calling {{classname}}->{{operationId}}: $e\n");
+}
+```
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+[[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)
+
+{{/operation}}
+{{/operations}}
--- a/modules/swagger-codegen/src/main/resources/dart/object_doc.mustache
+++ b/modules/swagger-codegen/src/main/resources/dart/object_doc.mustache
@@ -0,0 +1,16 @@
+{{#models}}{{#model}}# {{pubName}}.model.{{classname}}
+
+## Load the model package
+```dart
+import 'package:{{pubName}}/api.dart';
+```
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/vars}}
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+{{/model}}{{/models}}