loafle/openapi-generator-original
3
0
Fork 1
mirror of https://github.com/OpenAPITools/openapi-generator.git synced 2025-12-11 11:52:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Feature: Adds doc generation (#6570)

Browse Source 
Reference #2359
This commit is contained in:
Kenny Jones
2017-09-28 01:17:48 -04:00
committed by wing328
parent 2c7dcbe3e5
commit d04b7642f6
48 changed files with 1815 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/BashClientCodegen.java
View File

@@ -39,7 +39,8 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
protected String hostEnvironmentVariable;
protected String basicAuthEnvironmentVariable;
protected String apiKeyAuthEnvironmentVariable;
protected String apiDocPath = "docs/";
protected String modelDocPath = "docs/";
public static final String CURL_OPTIONS = "curlOptions";
public static final String PROCESS_MARKDOWN = "processMarkdown";
@@ -105,6 +106,13 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
apiTemplateFiles.clear();
/**
* docs files.
*/
modelDocTemplateFiles.put("model_doc.mustache", ".md");
apiDocTemplateFiles.put("api_doc.mustache", ".md");
/**
* Templates location for client script and bash completion template.
*/
@@ -169,6 +177,7 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
typeMapping.put("int", "integer");
typeMapping.put("float", "float");
typeMapping.put("number", "integer");
typeMapping.put("date", "string");
typeMapping.put("DateTime", "string");
typeMapping.put("long", "integer");
typeMapping.put("short", "integer");
@@ -185,12 +194,22 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
* are available in models, apis, and supporting files.
*/
additionalProperties.put("apiVersion", apiVersion);
// make api and model doc path available in mustache template
additionalProperties.put("apiDocPath", apiDocPath);
additionalProperties.put("modelDocPath", modelDocPath);
/**
* Language Specific Primitives. These types will not trigger imports by
* the client generator
*/
languageSpecificPrimitives = new HashSet<String>();
languageSpecificPrimitives.clear();
languageSpecificPrimitives.add("array");
languageSpecificPrimitives.add("map");
languageSpecificPrimitives.add("boolean");
languageSpecificPrimitives.add("integer");
languageSpecificPrimitives.add("float");
languageSpecificPrimitives.add("string");
languageSpecificPrimitives.add("binary");
}
@@ -239,15 +258,15 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
}
supportingFiles.add(new SupportingFile(
"client.mustache", "", scriptName));
"client.mustache", "", scriptName));
supportingFiles.add(new SupportingFile(
"bash-completion.mustache", "", scriptName+".bash-completion"));
"bash-completion.mustache", "", scriptName+".bash-completion"));
supportingFiles.add(new SupportingFile(
"zsh-completion.mustache", "", "_"+scriptName));
"zsh-completion.mustache", "", "_"+scriptName));
supportingFiles.add(new SupportingFile(
"README.mustache", "", "README.md"));
"README.mustache", "", "README.md"));
supportingFiles.add(new SupportingFile(
"Dockerfile.mustache", "", "Dockerfile"));
"Dockerfile.mustache", "", "Dockerfile"));
}
public void setCurlOptions(String curlOptions) {
@@ -314,6 +333,25 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
return outputFolder;
}
@Override
public String apiDocFileFolder() {
return (outputFolder + "/" + apiDocPath);
}
@Override
public String modelDocFileFolder() {
return (outputFolder + "/" + modelDocPath);
}
@Override
public String toModelDocFilename(String name) {
return toModelName(name);
}
@Override
public String toApiDocFilename(String name) {
return toApiName(name);
}
/**
* Optional - type declaration. This is a String which is used by the
@@ -355,8 +393,9 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
if(languageSpecificPrimitives.contains(type))
return type;
}
else
else {
type = swaggerType;
}
return toModelName(type);
}
@@ -656,4 +695,69 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
}
@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".equalsIgnoreCase(type)) {
if (example == null) {
example = p.paramName + "_example";
}
example = "'" + escapeText(example) + "'";
} else if ("integer".equals(type)) {
if (example == null) {
example = "56";
}
} else if ("float".equalsIgnoreCase(type)) {
if (example == null) {
example = "3.4";
}
} else if ("boolean".equalsIgnoreCase(type)) {
if (example == null) {
example = "True";
}
} else if ("file".equalsIgnoreCase(type)) {
if (example == null) {
example = "/path/to/file";
}
example = "'" + escapeText(example) + "'";
} else if ("date".equalsIgnoreCase(type)) {
if (example == null) {
example = "2013-10-20";
}
example = "'" + escapeText(example) + "'";
} else if ("datetime".equalsIgnoreCase(type)) {
if (example == null) {
example = "2013-10-20T19:20:30+01:00";
}
example = "'" + escapeText(example) + "'";
} else if (!languageSpecificPrimitives.contains(type)) {
// type is a model class, e.g. User
example = type;
} else {
LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
}
if (example == null) {
example = "NULL";
} else if (Boolean.TRUE.equals(p.isListContainer)) {
example = "[" + example + "]";
} else if (Boolean.TRUE.equals(p.isMapContainer)) {
example = "{'key': " + example + "}";
}
p.example = example;
}
}

40
modules/swagger-codegen/src/main/resources/bash/README.mustache
View File

@@ -3,7 +3,7 @@
## Overview
This is a Bash client script for accessing {{appName}} service.
The script uses cURL underneath for making all REST calls.
The script uses cURL underneath for making all REST calls.
## Usage
@@ -86,3 +86,41 @@ fi
### Zsh
In Zsh, the generated `_{{scriptName}}` Zsh completion file must be copied to one of the folders under `$FPATH` variable.
## Documentation for API Endpoints
All URIs are relative to *{{basePathWithoutHost}}*
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}}}{{#authorizationUrl}}
- **Authorization URL**: {{{authorizationUrl}}}{{/authorizationUrl}}{{#tokenUrl}}
- **Token URL**: {{{tokenUrl}}}{{/tokenUrl}}
- **Scopes**:{{^scopes}} N/A{{/scopes}}
{{#scopes}} - **{{{scope}}}**: {{{description}}}
{{/scopes}}
{{/isOAuth}}
{{/authMethods}}

47
modules/swagger-codegen/src/main/resources/bash/api_doc.mustache Normal file
View File

@@ -0,0 +1,47 @@
# {{classname}}{{#description}}
{{description}}{{/description}}
All URIs are relative to *{{basePathWithoutHost}}*
Method | HTTP request | Description
------------- | ------------- | -------------
{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
{{/operation}}{{/operations}}
{{#operations}}
{{#operation}}
## **{{{operationId}}}**
{{{summary}}}{{#notes}}
{{{notes}}}{{/notes}}
### Example
```bash
{{scriptName}} {{operationId}}{{#allParams}}{{#isPathParam}} {{baseName}}=value{{/isPathParam}}{{#isQueryParam}} {{#isContainer}} Specify as: {{#vendorExtensions}}{{#x-codegen-collection-multi}} {{baseName}}=value1 {{baseName}}=value2 {{baseName}}=...{{/x-codegen-collection-multi}}{{#x-codegen-collection-csv}} {{baseName}}="value1,value2,..."{{/x-codegen-collection-csv}}{{#x-codegen-collection-pipes}} {{baseName}}="value1|value2|..."{{/x-codegen-collection-pipes}}{{#x-codegen-collection-ssv}} {{baseName}}="value1 value2 ..."{{/x-codegen-collection-ssv}}{{#x-codegen-collection-tsv}} {{baseName}}="value1\\tvalue2\\t..."{{/x-codegen-collection-tsv}}{{/vendorExtensions}}{{/isContainer}}{{^isContainer}} {{baseName}}=value{{/isContainer}}{{/isQueryParam}}{{#isHeaderParam}} {{baseName}}:value{{/isHeaderParam}}{{#isBodyParam}}{{#vendorExtensions}}{{#x-codegen-body-example}} '{{{x-codegen-body-example}}}'{{/x-codegen-body-example}}{{/vendorExtensions}}{{/isBodyParam}}{{/allParams}}
```
### Parameters
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
Name | Type | Description | Notes
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{baseType}}.md){{/isPrimitiveType}}{{/isFile}} | {{{description}}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{defaultValue}}]{{/defaultValue}}
{{/allParams}}
### Return type
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}(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 Applicable{{/consumes}}
- **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not Applicable{{/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}}

6
modules/swagger-codegen/src/main/resources/bash/client.mustache
View File

@@ -577,9 +577,11 @@ EOF
{{#x-codegen-apikey-env}}echo -e " or export ${RED}{{x-codegen-apikey-env}}='<api-key>'${OFF}"{{/x-codegen-apikey-env}}
{{/isApiKey}}
{{#isOAuth}}
echo -e " - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"
echo -e " - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"{{#authorizationUrl}}
echo -e " Authorization URL: "
echo -e " * {{authorizationUrl}}"
echo -e " * {{authorizationUrl}}"{{/authorizationUrl}}{{#tokenUrl}}
echo -e " Token URL: "
echo -e " * {{tokenUrl}}"{{/tokenUrl}}
echo -e " Scopes:"
{{#scopes}}
echo -e " * {{scope}} - {{description}}"

11
modules/swagger-codegen/src/main/resources/bash/model_doc.mustache Normal file
View File

@@ -0,0 +1,11 @@
{{#models}}{{#model}}# {{name}}
## Properties
Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{title}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/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}}