Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Optimize the document generation template return interface definition to support future API interface error configuration additions. #809

Merged
merged 1 commit into from
Jun 8, 2024
Merged

feat: Optimize the document generation template return interface definition to support future API interface error configuration additions. #809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/main/java/com/ly/doc/builder/AdocDocBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
if (config.isAllInOne()) {
String docName = builderTemplate.allInOneDocName(config, INDEX_DOC, ".adoc");
apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/com/ly/doc/builder/ApiDocBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
if (config.isAllInOne()) {
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);
String docName = builderTemplate.allInOneDocName(config, "AllInOne" + version + DocGlobalConstants.MARKDOWN_EXTENSION, DocGlobalConstants.MARKDOWN_EXTENSION);
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/com/ly/doc/builder/DocBuilderTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ public Template buildAllRenderDocTemplate(List<ApiDoc> apiDocList, ApiConfig con
tpl.binding(TemplateVariable.LIST.getVariable(), apiDoc.getList());
}
// add jmeter prometheus listener
if (Objects.nonNull(config.getJmeter())){
if (Objects.nonNull(config.getJmeter())) {
tpl.binding(TemplateVariable.JMETER_PROMETHEUS_LISTENER.getVariable(), config.getJmeter().getAddPrometheusListener());
} else {
tpl.binding(TemplateVariable.JMETER_PROMETHEUS_LISTENER.getVariable(), Boolean.FALSE);
Expand Down Expand Up @@ -485,7 +485,7 @@ private List<ApiDoc> listOfApiData(ApiConfig config, JavaProjectBuilder javaProj
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
return docBuildTemplate.getApiData(configBuilder);
return docBuildTemplate.getApiData(configBuilder).getApiDatas();
}

}
2 changes: 1 addition & 1 deletion src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
Template indexCssTemplate = BeetlTemplateUtil.getByName(DocGlobalConstants.ALL_IN_ONE_CSS);
FileUtil.nioWriteFile(indexCssTemplate.render(), config.getOutPath() + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.ALL_IN_ONE_CSS_OUT);
BaseDocBuilderTemplate.copyJarFile("js/" + DocGlobalConstants.HIGH_LIGHT_JS, config.getOutPath() + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.HIGH_LIGHT_JS);
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/com/ly/doc/builder/JMeterBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);
String docName;
if (StringUtil.isNotEmpty(config.getProjectName())) {
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ private static void postManCreate(ApiConfig config, ProjectDocConfigBuilder conf
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
config.setShowJavaType(true);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
RequestItem requestItem = new RequestItem();
requestItem.setInfo(new InfoBean(config.getProjectName()));
List<ItemBean> itemBeans = new ArrayList<>();
Expand Down
5 changes: 3 additions & 2 deletions src/main/java/com/ly/doc/builder/TornaBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
import com.ly.doc.helper.JavaProjectBuilderHelper;
import com.ly.doc.model.ApiConfig;
import com.ly.doc.model.ApiDoc;
import com.ly.doc.model.ApiSchema;
import com.ly.doc.model.torna.Apis;
import com.ly.doc.model.torna.TornaApi;
import com.ly.doc.template.IDocBuildTemplate;
Expand Down Expand Up @@ -69,8 +70,8 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
ApiSchema<ApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = docBuildTemplate.handleApiGroup(apiSchema.getApiDatas(), config);
buildTorna(apiDocList, config, javaProjectBuilder);
}

Expand Down
4 changes: 3 additions & 1 deletion src/main/java/com/ly/doc/builder/WordDocBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
import com.ly.doc.helper.JavaProjectBuilderHelper;
import com.ly.doc.model.ApiConfig;
import com.ly.doc.model.ApiDoc;
import com.ly.doc.model.ApiSchema;
import com.ly.doc.template.IDocBuildTemplate;
import com.power.common.util.DateTimeUtil;
import com.power.common.util.FileUtil;
Expand Down Expand Up @@ -78,7 +79,8 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
ApiSchema<ApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
List<ApiDoc> apiDocList = apiSchema.getApiDatas();

if (config.isAllInOne()) {
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);
Expand Down
9 changes: 4 additions & 5 deletions src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,7 @@
import com.ly.doc.constants.FrameworkEnum;
import com.ly.doc.constants.TemplateVariable;
import com.ly.doc.factory.BuildTemplateFactory;
import com.ly.doc.model.ApiConfig;
import com.ly.doc.model.ApiDocDict;
import com.ly.doc.model.ApiErrorCode;
import com.ly.doc.model.*;
import com.ly.doc.model.javadoc.JavadocApiAllData;
import com.ly.doc.model.javadoc.JavadocApiDoc;
import com.ly.doc.template.IDocBuildTemplate;
Expand Down Expand Up @@ -201,15 +199,16 @@ private List<JavadocApiDoc> listOfApiData(ApiConfig config, JavaProjectBuilder j
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<JavadocApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
return docBuildTemplate.getApiData(configBuilder);
ApiSchema<JavadocApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
return apiSchema.getApiDatas();
}

public List<JavadocApiDoc> getJavadocApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) {
config.setShowJavaType(true);
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
IDocBuildTemplate<JavadocApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
return docBuildTemplate.getApiData(configBuilder);
return docBuildTemplate.getApiData(configBuilder).getApiDatas();
}

}
86 changes: 60 additions & 26 deletions src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,7 @@

import com.ly.doc.builder.DocBuilderTemplate;
import com.ly.doc.builder.ProjectDocConfigBuilder;
import com.ly.doc.constants.ComponentTypeEnum;
import com.ly.doc.constants.MediaType;
import com.ly.doc.constants.Methods;
import com.ly.doc.constants.ParamTypeConstants;
import com.ly.doc.constants.*;
import com.ly.doc.factory.BuildTemplateFactory;
import com.ly.doc.model.*;
import com.ly.doc.model.openapi.OpenApiTag;
Expand Down Expand Up @@ -68,20 +65,21 @@ public void setComponentKey(String componentKey) {
/**
* Create OpenAPI definition
*
* @param apiConfig Configuration of smart-doc
* @param apiDocList List of API DOC
* @param apiConfig Configuration of smart-doc
* @param apiSchema Project API schema
*/
abstract void openApiCreate(ApiConfig apiConfig, List<ApiDoc> apiDocList);
abstract void openApiCreate(ApiConfig apiConfig, ApiSchema<ApiDoc> apiSchema);

/**
* Build request
*
* @param apiConfig Configuration of smart-doc
* @param apiMethodDoc Data of method
* @param apiDoc singe api doc
* @param apiConfig Configuration of smart-doc
* @param apiMethodDoc Data of method
* @param apiDoc singe api doc
* @param apiExceptionStatuses Exception status list
* @return Map of request urls
*/
abstract Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc);
abstract Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List<ApiExceptionStatus> apiExceptionStatuses);

/**
* response body
Expand All @@ -102,19 +100,19 @@ public void setComponentKey(String componentKey) {
/**
* Build openapi paths
*
* @param apiConfig Configuration of smart-doc
* @param apiDocList List of API DOC
* @param tags tags
* @param apiConfig Configuration of smart-doc
* @param apiSchema Project API schema
* @param tags tags
* @return Map of paths
*/
public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocList, Set<OpenApiTag> tags) {
public Map<String, Object> buildPaths(ApiConfig apiConfig, ApiSchema<ApiDoc> apiSchema, Set<OpenApiTag> tags) {
Map<String, Object> pathMap = new HashMap<>(500);
Set<ApiMethodDoc> methodDocs = DocMapping.METHOD_DOCS;
for (ApiMethodDoc methodDoc : methodDocs) {
String[] paths = methodDoc.getPath().split(";");
for (String path : paths) {
path = path.trim();
Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc());
Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc(), apiSchema.getApiExceptionStatuses());
if (!pathMap.containsKey(path)) {
pathMap.put(path, request);
} else {
Expand Down Expand Up @@ -142,9 +140,9 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocLi
* @param apiDoc ApiDoc
* @return Map of path urls
*/
public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc) {
public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List<ApiExceptionStatus> apiExceptionStatuses) {
Map<String, Object> request = new HashMap<>(4);
request.put(apiMethodDoc.getType().toLowerCase(), buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc));
request.put(apiMethodDoc.getType().toLowerCase(), buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc, apiExceptionStatuses));
return request;
}

Expand Down Expand Up @@ -348,11 +346,12 @@ public static Map<String, Object> buildParametersSchema(ApiReqParam header) {
/**
* build response
*
* @param apiMethodDoc ApiMethodDoc
* @param apiConfig ApiConfig
* @param apiMethodDoc ApiMethodDoc
* @param apiConfig ApiConfig
* @param apiExceptionStatuses apiExceptionStatuses
* @return response info
*/
public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc) {
public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, List<ApiExceptionStatus> apiExceptionStatuses) {
Map<String, Object> response = new HashMap<>(10);
response.put("200", buildResponsesBody(apiConfig, apiMethodDoc));
return response;
Expand Down Expand Up @@ -457,22 +456,19 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
propertiesData.put("format", "binary");
}
if ("object".equals(apiParam.getType())) {
propertiesData.put("description", apiParam.getDesc() + "(object)");
if (CollectionUtil.isNotEmpty(apiParam.getChildren())) {
propertiesData.put("type", "object");
propertiesData.put("description", apiParam.getDesc() + "(object)");
if (!apiParam.isSelfReferenceLoop()) {
String childSchemaName = OpenApiSchemaUtil.getClassNameFromParams(apiParam.getChildren());
if (childSchemaName.contains(OpenApiSchemaUtil.NO_BODY_PARAM)) {
propertiesData.put("type", "object");
propertiesData.put("description", apiParam.getDesc() + "(object)");
} else {
component.put(childSchemaName, buildProperties(apiParam.getChildren(), component, isResp));
propertiesData.put("$ref", componentKey + childSchemaName);
}
}
} else {
propertiesData.put("type", "object");
propertiesData.put("description", apiParam.getDesc() + "(object)");
}
}
if (apiParam.getExtensions() != null && !apiParam.getExtensions().isEmpty()) {
Expand All @@ -482,14 +478,47 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
return propertiesData;
}

/**
* Builds component data for API documentation.
* This method iterates through all API documentation entries to extract request and response parameter information,
* and organizes them into OpenAPI component schemas.
*
* @param apiDocs List of API documentation, containing multiple API method descriptions.
* @return Returns a map containing all component schemas.
*/
public Map<String, Object> buildComponentData(List<ApiDoc> apiDocs) {
Map<String, Object> component = new HashMap<>(16);
component.put(DocGlobalConstants.DEFAULT_PRIMITIVE, STRING_COMPONENT);
apiDocs.forEach(
a -> {
List<ApiMethodDoc> apiMethodDocs = a.getList();
apiMethodDocs.forEach(
method -> {
//request components
String requestSchema = OpenApiSchemaUtil.getClassNameFromParams(method.getRequestParams());
List<ApiParam> requestParams = method.getRequestParams();
Map<String, Object> prop = buildProperties(requestParams, component, false);
component.put(requestSchema, prop);
//response components
List<ApiParam> responseParams = method.getResponseParams();
String responseSchemaName = OpenApiSchemaUtil.getClassNameFromParams(method.getResponseParams());
component.put(responseSchemaName, buildProperties(responseParams, component, true));
}
);
}
);
component.remove(OpenApiSchemaUtil.NO_BODY_PARAM);
return component;
}

/**
* Get a list of OpenAPI's document data
*
* @param config Configuration of smart-doc
* @param projectBuilder JavaDocBuilder of QDox
* @return List of OpenAPI's document data
*/
public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
public ApiSchema<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
config.setShowJavaType(false);
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config, Boolean.TRUE);
Expand All @@ -499,4 +528,9 @@ public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectB
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
return docBuildTemplate.getApiData(configBuilder);
}

public static Map<String, Object> buildErrorStatusResponse(ApiConfig apiConfig, List<ApiExceptionStatus> apiExceptionStatuses) {
// TODO
return null;
}
}
Loading
Loading