loafle/openapi-generator
3
0
Fork 0
forked from loafle/openapi-generator-original
Code Pull Requests Activity

Add Markdown docs to Java (default) client

Browse Source
This commit is contained in:
xhh
2016-03-22 17:38:56 +08:00
parent a44918f53a
commit 1510684093
5 changed files with 194 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavaClientCodegen.java
View File

@@ -42,6 +42,8 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
protected Boolean serializableModel = false;
protected boolean serializeBigDecimalAsString = false;
protected boolean useRxJava = false;
protected String apiDocPath = "docs/";
protected String modelDocPath = "docs/";
public JavaClientCodegen() {
super();
@@ -205,6 +207,10 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
additionalProperties.put(FULL_JAVA_UTIL, fullJavaUtil);
additionalProperties.put("javaUtilPrefix", javaUtilPrefix);
// make api and model doc path available in mustache template
additionalProperties.put("apiDocPath", apiDocPath);
additionalProperties.put("modelDocPath", modelDocPath);
importMapping.put("List", "java.util.List");
if (fullJavaUtil) {
@@ -266,7 +272,10 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
}
// library-specific files
if ("okhttp-gson".equals(getLibrary())) {
if (StringUtils.isEmpty(getLibrary())) {
modelDocTemplateFiles.put("model_doc.mustache", ".md");
apiDocTemplateFiles.put("api_doc.mustache", ".md");
} else if ("okhttp-gson".equals(getLibrary())) {
// the "okhttp-gson" library template requires "ApiCallback.mustache" for async call
supportingFiles.add(new SupportingFile("ApiCallback.mustache", invokerFolder, "ApiCallback.java"));
supportingFiles.add(new SupportingFile("ApiResponse.mustache", invokerFolder, "ApiResponse.java"));
@@ -350,6 +359,26 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
return outputFolder + "/" + sourceFolder + "/" + modelPackage().replace('.', '/');
}
@Override
public String apiDocFileFolder() {
return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
}
@Override
public String modelDocFileFolder() {
return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
}
@Override
public String toApiDocFilename(String name) {
return toApiName(name);
}
@Override
public String toModelDocFilename(String name) {
return toModelName(name);
}
@Override
public String toVarName(String name) {
// sanitize name
@@ -494,6 +523,69 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
return super.toDefaultValue(p);
}
@Override
public void setParameterExampleValue(CodegenParameter p) {
String example;
if (p.defaultValue == null) {
example = p.example;
} else {
example = p.defaultValue;
}
String type = p.baseType;
if (type == null) {
type = p.dataType;
}
if ("String".equals(type)) {
if (example == null) {
example = p.paramName + "_example";
}
example = "\"" + escapeText(example) + "\"";
} else if ("Integer".equals(type) || "Short".equals(type)) {
if (example == null) {
example = "56";
}
} else if ("Long".equals(type)) {
if (example == null) {
example = "56L";
}
} else if ("Float".equals(type)) {
if (example == null) {
example = "3.4F";
}
} else if ("Double".equals(type)) {
if (example == null) {
example = "3.4D";
}
} else if ("Boolean".equals(type)) {
if (example == null) {
example = "true";
}
} else if ("File".equals(type)) {
if (example == null) {
example = "/path/to/file";
}
example = "new File(\"" + escapeText(example) + "\")";
} else if ("Date".equals(type)) {
example = "new Date()";
} else if (!languageSpecificPrimitives.contains(type)) {
// type is a model class, e.g. User
example = "new " + type + "()";
}
if (example == null) {
example = "null";
} else if (Boolean.TRUE.equals(p.isListContainer)) {
example = "Arrays.asList(" + example + ")";
} else if (Boolean.TRUE.equals(p.isMapContainer)) {
example = "new HashMap()";
}
p.example = example;
}
@Override
public String getSwaggerType(Property p) {
String swaggerType = super.getSwaggerType(p);

20
modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavascriptClientCodegen.java
View File

@@ -524,26 +524,6 @@ public class JavascriptClientCodegen extends DefaultCodegen implements CodegenCo
type = p.dataType;
}
typeMapping.put("array", "Array");
typeMapping.put("List", "Array");
typeMapping.put("map", "Object");
typeMapping.put("object", "Object");
typeMapping.put("boolean", "Boolean");
typeMapping.put("char", "String");
typeMapping.put("string", "String");
typeMapping.put("short", "Integer");
typeMapping.put("int", "Integer");
typeMapping.put("integer", "Integer");
typeMapping.put("long", "Integer");
typeMapping.put("float", "Number");
typeMapping.put("double", "Number");
typeMapping.put("number", "Number");
typeMapping.put("DateTime", "Date");
typeMapping.put("Date", "Date");
typeMapping.put("file", "File");
// binary not supported in JavaScript client right now, using String as a workaround
typeMapping.put("binary", "String");
if ("String".equals(type)) {
if (example == null) {
example = p.paramName + "_example";

82
modules/swagger-codegen/src/main/resources/Java/api_doc.mustache Normal file
View File

@@ -0,0 +1,82 @@
# {{classname}}{{#description}}
{{description}}{{/description}}
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}}
<a name="{{operationId}}"></a>
# **{{operationId}}**
> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
{{summary}}{{#notes}}
{{notes}}{{/notes}}
### Example
```java
// Import classes:{{#hasAuthMethods}}
//import {{{invokerPackage}}}.ApiClient;{{/hasAuthMethods}}
//import {{{invokerPackage}}}.ApiException;{{#hasAuthMethods}}
//import {{{invokerPackage}}}.Configuration;
//import {{{invokerPackage}}}.auth.*;{{/hasAuthMethods}}
//import {{{package}}}.{{{classname}}};
{{#hasAuthMethods}}
ApiClient defaultClient = Configuration.getDefaultApiClient();
{{#authMethods}}{{#isBasic}}
// Configure HTTP basic authorization: {{{name}}}
HttpBasicAuth {{{name}}} = (HttpBasicAuth) defaultClient.getAuthentication("{{{name}}}");
{{{name}}}.setUsername("YOUR USERNAME");
{{{name}}}.setPassword("YOUR PASSWORD");{{/isBasic}}{{#isApiKey}}
// Configure API key authorization: {{{name}}}
ApiKeyAuth {{{name}}} = defaultClient.getAuthentication("{{{name}}}");
{{{name}}}.setApiKey("YOUR API KEY");
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//{{{name}}}.setApiKeyPrefix("Token");{{/isApiKey}}{{#isOAuth}}
// Configure OAuth2 access token for authorization: {{{name}}}
OAuth {{{name}}} = defaultClient.getAuthentication("{{{name}}}");
{{{name}}}.setAccessToken("YOUR ACCESS TOKEN");{{/isOAuth}}
{{/authMethods}}
{{/hasAuthMethods}}
{{{classname}}} apiInstance = new {{{classname}}}();
{{#allParams}}
{{{dataType}}} {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
{{/allParams}}
try {
{{#returnType}}{{{returnType}}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
System.out.println(result);{{/returnType}}
} catch (ApiException e) {
System.err.println("Exception when calling {{{classname}}}#{{{operationId}}}");
e.printStackTrace();
}
```
### Parameters
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
Name | Type | Description | Notes
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
{{#allParams}} **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^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}}null (empty response body){{/returnType}}
### Authorization
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../README.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}}
### HTTP reuqest headers
- **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
- **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
{{/operation}}
{{/operations}}

9
modules/swagger-codegen/src/main/resources/Java/model_doc.mustache Normal file
View File

@@ -0,0 +1,9 @@
{{#models}}{{#model}}# {{classname}}
## 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}}
{{/model}}{{/models}}

20
modules/swagger-codegen/src/main/resources/Javascript/api_doc.mustache
View File

@@ -12,7 +12,7 @@ Method | HTTP request | Description
{{#operation}}
<a name="{{operationId}}"></a>
# **{{operationId}}**
> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}{{#hasParams}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}){{/hasParams}}
> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}})
{{summary}}{{#notes}}
@@ -26,25 +26,25 @@ var defaultClient = {{{moduleName}}}.ApiClient.default;
{{#authMethods}}{{#isBasic}}
// Configure HTTP basic authorization: {{{name}}}
var {{{name}}} = defaultClient.authentications['{{{name}}}'];
{{{name}}}.username = 'YOUR USERNAME'
{{{name}}}.password = 'YOUR PASSWORD'{{/isBasic}}{{#isApiKey}}
{{{name}}}.username = 'YOUR USERNAME';
{{{name}}}.password = 'YOUR PASSWORD';{{/isBasic}}{{#isApiKey}}
// Configure API key authorization: {{{name}}}
var {{{name}}} = defaultClient.authentications['{{{name}}}'];
{{{name}}}.apiKey = "YOUR API KEY"
{{{name}}}.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//{{{name}}}.apiKeyPrefix['{{{keyParamName}}}'] = "Token"{{/isApiKey}}{{#isOAuth}}
//{{{name}}}.apiKeyPrefix = 'Token';{{/isApiKey}}{{#isOAuth}}
// Configure OAuth2 access token for authorization: {{{name}}}
var {{{name}}} = defaultClient.authentications['{{{name}}}'];
{{{name}}}.accessToken = "YOUR ACCESS TOKEN"{{/isOAuth}}
{{{name}}}.accessToken = 'YOUR ACCESS TOKEN';{{/isOAuth}}
{{/authMethods}}
{{/hasAuthMethods}}
var apiInstance = new {{{moduleName}}}.{{{classname}}}(){{#hasParams}}
var apiInstance = new {{{moduleName}}}.{{{classname}}}();{{#hasParams}}
{{#vendorExtensions.x-codegen-hasRequiredParams}}{{#allParams}}{{#required}}
var {{{paramName}}} = {{{example}}}; // {{=< >=}}{<&dataType>}<={{ }}=> {{{description}}}
var {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
{{/required}}{{/allParams}}{{/vendorExtensions.x-codegen-hasRequiredParams}}{{#hasOptionalParams}}
var opts = { {{#allParams}}{{^required}}
'{{{paramName}}}': {{{example}}}{{#vendorExtensions.x-codegen-hasMoreOptional}},{{/vendorExtensions.x-codegen-hasMoreOptional}} // {{=< >=}}{<&dataType>}<={{ }}=> {{{description}}}{{/required}}{{/allParams}}
'{{{paramName}}}': {{{example}}}{{#vendorExtensions.x-codegen-hasMoreOptional}},{{/vendorExtensions.x-codegen-hasMoreOptional}} // {{{dataType}}} | {{{description}}}{{/required}}{{/allParams}}
};{{/hasOptionalParams}}{{/hasParams}}
{{#usePromises}}
apiInstance.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}).then(function({{#returnType}}data{{/returnType}}) {
@@ -61,7 +61,7 @@ var callback = function(error, data, response) {
{{#returnType}}console.log('API called successfully. Returned data: ' + data);{{/returnType}}{{^returnType}}console.log('API called successfully.');{{/returnType}}
}
};
api.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}{{#hasParams}}, {{/hasParams}}callback);
apiInstance.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}{{#hasParams}}, {{/hasParams}}callback);
{{/usePromises}}
```