From 69508d38fab625c001026f674181993f649e7e50 Mon Sep 17 00:00:00 2001 From: monicataina Date: Thu, 1 Feb 2024 17:23:08 +0200 Subject: [PATCH 1/3] Update CppUE4ClientCodegen.java to generate docs Add support for the global properties: apiDocs and modelDocs. In case the files are generated enabling them, it will search for api_doc.mustache and model_doc.mustache to generate md documentation files. Add an optional property for the generating call: generateReadme = true. By default, it's false and it can be omitted, so that it won't be a breaking change. If this option is used, then it will search for README.mustache and it will generate index.md file. The "index" name was chosen so that mkdocs can be used including multiple services generated via OpenAPI and this way can create a page for each of them and use the [mkdocs index section feature](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages) --- .../languages/CppUE4ClientCodegen.java | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CppUE4ClientCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CppUE4ClientCodegen.java index 9ac111edaf33..af2b5f9f6484 100644 --- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CppUE4ClientCodegen.java +++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CppUE4ClientCodegen.java @@ -21,6 +21,7 @@ import org.openapitools.codegen.CodegenConstants; import org.openapitools.codegen.CodegenType; import org.openapitools.codegen.SupportingFile; +import org.openapitools.codegen.meta.features.*; // to use DocumentationFeature import org.openapitools.codegen.meta.GeneratorMetadata; import org.openapitools.codegen.meta.Stability; import org.openapitools.codegen.utils.ModelUtils; @@ -49,6 +50,7 @@ public class CppUE4ClientCodegen extends AbstractCppCodegen { protected Set systemIncludes = new HashSet<>(); protected String cppNamespace = unrealModuleName; protected boolean optionalProjectFileFlag = true; + protected boolean generateReadme = false; public CppUE4ClientCodegen() { super(); @@ -60,6 +62,30 @@ public CppUE4ClientCodegen() { // set the output folder here outputFolder = "generated-code/cpp-ue4"; + //generate Readme doc and get the other feature from cpp codegen + modifyFeatureSet(features -> features + .includeDocumentationFeatures(DocumentationFeature.Readme) + .securityFeatures(EnumSet.of( + SecurityFeature.BasicAuth, + SecurityFeature.OAuth2_Implicit, + SecurityFeature.ApiKey + )) + .excludeGlobalFeatures( + GlobalFeature.XMLStructureDefinitions, + GlobalFeature.Callbacks, + GlobalFeature.LinkObjects, + GlobalFeature.ParameterStyling, + GlobalFeature.MultiServer + ) + .includeSchemaSupportFeatures( + SchemaSupportFeature.Polymorphism + ) + .excludeParameterFeatures( + ParameterFeature.Cookie + ) + ); + + // set modelNamePrefix as default for cpp-ue4 if ("".equals(modelNamePrefix)) { modelNamePrefix = unrealModuleName; @@ -100,6 +126,14 @@ public CppUE4ClientCodegen() { "api-operations-source.mustache", // the template to use ".cpp"); // the extension for each file to write + modelDocTemplateFiles.put( + "model_doc.mustache", // the template to use + ".md"); // the extension for each file to write + + apiDocTemplateFiles.put( + "api_doc.mustache", // the template to use + ".md"); // the extension for each file to write + /* * Template Location. This is the location which templates will be read from. The generator * will use the resource stream to attempt to read the templates. @@ -239,6 +273,13 @@ public void processOpts() { } importMapping.put("HttpFileInput", "#include \"" + modelNamePrefix + "Helpers.h\""); + + if (additionalProperties.containsKey("generateReadme")) { // check if generateReadme parameter was used to enable/disable generation of index.md file + generateReadme = Boolean.parseBoolean(additionalProperties.get("generateReadme").toString()); + } + if (generateReadme) { //if files were generated using generateReadme=true, then generate index.md + supportingFiles.add(new SupportingFile("README.mustache", "index.md")); + } } } From 152fbe526c03ab29ddfebde7fc08edb7365d9fee Mon Sep 17 00:00:00 2001 From: monicataina Date: Tue, 13 Feb 2024 21:11:11 +0200 Subject: [PATCH 2/3] Add files via upload --- .../main/resources/cpp-ue4/api_doc.mustache | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 modules/openapi-generator/src/main/resources/cpp-ue4/api_doc.mustache diff --git a/modules/openapi-generator/src/main/resources/cpp-ue4/api_doc.mustache b/modules/openapi-generator/src/main/resources/cpp-ue4/api_doc.mustache new file mode 100644 index 000000000000..5695b461de79 --- /dev/null +++ b/modules/openapi-generator/src/main/resources/cpp-ue4/api_doc.mustache @@ -0,0 +1,61 @@ +# {{packageName}}.{{apiPackage}}.{{classname}}{{#description}} +{{.}}{{/description}} + +All URIs are relative to *<{{{basePath}}}>* + +| Method | HTTP request | Description | +|--------|--------------|-------------| +{{#operations}} +{{#operation}} +| [**{{operationId}}**]({{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{summary}} | +{{/operation}} +{{/operations}} + +{{#operations}} +{{#operation}} + +# **{{{operationId}}}** +> {{returnType}}{{^returnType}}void{{/returnType}} {{operationId}} ({{#allParams}}{{{dataType}}} {{paramName}}{{^required}}{{#optionalMethodArgument}} = null{{/optionalMethodArgument}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}}) + +{{{summary}}}{{#notes}} + +{{{.}}}{{/notes}} + + +### 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}}**]({{#isContainer}}{{baseType}}{{/isContainer}}{{^isContainer}}{{dataType}}{{/isContainer}}.md){{/isFile}}{{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{.}}]{{/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}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}} +- **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}} + +{{#responses.0}} +### HTTP response details + +| Status code | Description | Response headers | +|-------------|-------------|------------------| +{{#responses}} +| **{{code}}** | {{message}} | {{#headers}} * {{baseName}} - {{description}}
{{/headers}}{{^headers.0}} - {{/headers.0}} | +{{/responses}} +{{/responses.0}} + +[[Back to top]](#) [[Back to API list]](../{{#useGenericHost}}../{{/useGenericHost}}README.md#documentation-for-api-endpoints) [[Back to Model list]](../{{#useGenericHost}}../{{/useGenericHost}}README.md#documentation-for-models) [[Back to README]](../{{#useGenericHost}}../{{/useGenericHost}}README.md) + +{{/operation}} +{{/operations}} From 42cd70ae103b74c21014f1bf3ae38d0a065e87fe Mon Sep 17 00:00:00 2001 From: monicataina Date: Thu, 15 Feb 2024 10:11:05 +0200 Subject: [PATCH 3/3] Add files via upload --- .../main/resources/cpp-ue4/model_doc.mustache | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 modules/openapi-generator/src/main/resources/cpp-ue4/model_doc.mustache diff --git a/modules/openapi-generator/src/main/resources/cpp-ue4/model_doc.mustache b/modules/openapi-generator/src/main/resources/cpp-ue4/model_doc.mustache new file mode 100644 index 000000000000..971511e5fa1c --- /dev/null +++ b/modules/openapi-generator/src/main/resources/cpp-ue4/model_doc.mustache @@ -0,0 +1,22 @@ +{{#models}} +{{#model}} +# {{{packageName}}}.{{modelPackage}}.{{{classname}}} +{{#description}}{{&description}} +{{/description}} + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +{{#parent}} +{{#parentVars}} +**{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} +{{/parentVars}} +{{/parent}} +{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}} +{{/vars}} + +[[Back to Model list]](../{{#useGenericHost}}../{{/useGenericHost}}README.md#documentation-for-models) [[Back to API list]](../{{#useGenericHost}}../{{/useGenericHost}}README.md#documentation-for-api-endpoints) [[Back to README]](../{{#useGenericHost}}../{{/useGenericHost}}README.md) + +{{/model}} +{{/models}} \ No newline at end of file