Skip to content
This repository was archived by the owner on Dec 4, 2025. It is now read-only.

Commit ac56941

Browse files
shalousunshalousun
authored
Merge pull request #809 from shalousun/master
feat: Optimize the document generation template return interface definition to support future API interface error configuration additions.
2 parents 94426aa + 4b699e4 commit ac56941

28 files changed

+424
-209
lines changed

‎src/main/java/com/ly/doc/builder/AdocDocBuilder.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
6666
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
6767
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
6868
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
69-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
69+
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
7070
if (config.isAllInOne()) {
7171
String docName = builderTemplate.allInOneDocName(config, INDEX_DOC, ".adoc");
7272
apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);

‎src/main/java/com/ly/doc/builder/ApiDocBuilder.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
6363
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
6464
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
6565
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
66-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
66+
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
6767
if (config.isAllInOne()) {
6868
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);
6969
String docName = builderTemplate.allInOneDocName(config, "AllInOne" + version + DocGlobalConstants.MARKDOWN_EXTENSION, DocGlobalConstants.MARKDOWN_EXTENSION);

‎src/main/java/com/ly/doc/builder/DocBuilderTemplate.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ public Template buildAllRenderDocTemplate(List<ApiDoc> apiDocList, ApiConfig con
182182
tpl.binding(TemplateVariable.LIST.getVariable(), apiDoc.getList());
183183
}
184184
// add jmeter prometheus listener
185-
if (Objects.nonNull(config.getJmeter())){
185+
if (Objects.nonNull(config.getJmeter())) {
186186
tpl.binding(TemplateVariable.JMETER_PROMETHEUS_LISTENER.getVariable(), config.getJmeter().getAddPrometheusListener());
187187
} else {
188188
tpl.binding(TemplateVariable.JMETER_PROMETHEUS_LISTENER.getVariable(), Boolean.FALSE);
@@ -485,7 +485,7 @@ private List<ApiDoc> listOfApiData(ApiConfig config, JavaProjectBuilder javaProj
485485
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
486486
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
487487
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
488-
return docBuildTemplate.getApiData(configBuilder);
488+
return docBuildTemplate.getApiData(configBuilder).getApiDatas();
489489
}
490490

491491
}

‎src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
6868
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
6969
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
7070
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
71-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
71+
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
7272
Template indexCssTemplate = BeetlTemplateUtil.getByName(DocGlobalConstants.ALL_IN_ONE_CSS);
7373
FileUtil.nioWriteFile(indexCssTemplate.render(), config.getOutPath() + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.ALL_IN_ONE_CSS_OUT);
7474
BaseDocBuilderTemplate.copyJarFile("js/" + DocGlobalConstants.HIGH_LIGHT_JS, config.getOutPath() + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.HIGH_LIGHT_JS);

‎src/main/java/com/ly/doc/builder/JMeterBuilder.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
6666
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
6767
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
6868
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
69-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
69+
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
7070
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);
7171
String docName;
7272
if (StringUtil.isNotEmpty(config.getProjectName())) {

‎src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ private static void postManCreate(ApiConfig config, ProjectDocConfigBuilder conf
251251
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
252252
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
253253
config.setShowJavaType(true);
254-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
254+
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder).getApiDatas();
255255
RequestItem requestItem = new RequestItem();
256256
requestItem.setInfo(new InfoBean(config.getProjectName()));
257257
List<ItemBean> itemBeans = new ArrayList<>();

‎src/main/java/com/ly/doc/builder/TornaBuilder.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
import com.ly.doc.helper.JavaProjectBuilderHelper;
2626
import com.ly.doc.model.ApiConfig;
2727
import com.ly.doc.model.ApiDoc;
28+
import com.ly.doc.model.ApiSchema;
2829
import com.ly.doc.model.torna.Apis;
2930
import com.ly.doc.model.torna.TornaApi;
3031
import com.ly.doc.template.IDocBuildTemplate;
@@ -69,8 +70,8 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
6970
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
7071
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
7172
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
72-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
73-
apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
73+
ApiSchema<ApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
74+
List<ApiDoc> apiDocList = docBuildTemplate.handleApiGroup(apiSchema.getApiDatas(), config);
7475
buildTorna(apiDocList, config, javaProjectBuilder);
7576
}
7677

‎src/main/java/com/ly/doc/builder/WordDocBuilder.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
import com.ly.doc.helper.JavaProjectBuilderHelper;
2626
import com.ly.doc.model.ApiConfig;
2727
import com.ly.doc.model.ApiDoc;
28+
import com.ly.doc.model.ApiSchema;
2829
import com.ly.doc.template.IDocBuildTemplate;
2930
import com.power.common.util.DateTimeUtil;
3031
import com.power.common.util.FileUtil;
@@ -78,7 +79,8 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
7879
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
7980
IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
8081
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
81-
List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
82+
ApiSchema<ApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
83+
List<ApiDoc> apiDocList = apiSchema.getApiDatas();
8284

8385
if (config.isAllInOne()) {
8486
String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DocGlobalConstants.DATE_FORMAT_YYYY_MM_DD_HH_MM);

‎src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,7 @@
2727
import com.ly.doc.constants.FrameworkEnum;
2828
import com.ly.doc.constants.TemplateVariable;
2929
import com.ly.doc.factory.BuildTemplateFactory;
30-
import com.ly.doc.model.ApiConfig;
31-
import com.ly.doc.model.ApiDocDict;
32-
import com.ly.doc.model.ApiErrorCode;
30+
import com.ly.doc.model.*;
3331
import com.ly.doc.model.javadoc.JavadocApiAllData;
3432
import com.ly.doc.model.javadoc.JavadocApiDoc;
3533
import com.ly.doc.template.IDocBuildTemplate;
@@ -201,15 +199,16 @@ private List<JavadocApiDoc> listOfApiData(ApiConfig config, JavaProjectBuilder j
201199
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
202200
IDocBuildTemplate<JavadocApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
203201
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
204-
return docBuildTemplate.getApiData(configBuilder);
202+
ApiSchema<JavadocApiDoc> apiSchema = docBuildTemplate.getApiData(configBuilder);
203+
return apiSchema.getApiDatas();
205204
}
206205

207206
public List<JavadocApiDoc> getJavadocApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) {
208207
config.setShowJavaType(true);
209208
ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
210209
IDocBuildTemplate<JavadocApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
211210
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
212-
return docBuildTemplate.getApiData(configBuilder);
211+
return docBuildTemplate.getApiData(configBuilder).getApiDatas();
213212
}
214213

215214
}

‎src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java‎

Lines changed: 60 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,7 @@
2626

2727
import com.ly.doc.builder.DocBuilderTemplate;
2828
import com.ly.doc.builder.ProjectDocConfigBuilder;
29-
import com.ly.doc.constants.ComponentTypeEnum;
30-
import com.ly.doc.constants.MediaType;
31-
import com.ly.doc.constants.Methods;
32-
import com.ly.doc.constants.ParamTypeConstants;
29+
import com.ly.doc.constants.*;
3330
import com.ly.doc.factory.BuildTemplateFactory;
3431
import com.ly.doc.model.*;
3532
import com.ly.doc.model.openapi.OpenApiTag;
@@ -68,20 +65,21 @@ public void setComponentKey(String componentKey) {
6865
/**
6966
* Create OpenAPI definition
7067
*
71-
* @param apiConfig Configuration of smart-doc
72-
* @param apiDocList List of API DOC
68+
* @param apiConfig Configuration of smart-doc
69+
* @param apiSchema Project API schema
7370
*/
74-
abstract void openApiCreate(ApiConfig apiConfig, List<ApiDoc> apiDocList);
71+
abstract void openApiCreate(ApiConfig apiConfig, ApiSchema<ApiDoc> apiSchema);
7572

7673
/**
7774
* Build request
7875
*
79-
* @param apiConfig Configuration of smart-doc
80-
* @param apiMethodDoc Data of method
81-
* @param apiDoc singe api doc
76+
* @param apiConfig Configuration of smart-doc
77+
* @param apiMethodDoc Data of method
78+
* @param apiDoc singe api doc
79+
* @param apiExceptionStatuses Exception status list
8280
* @return Map of request urls
8381
*/
84-
abstract Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc);
82+
abstract Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List<ApiExceptionStatus> apiExceptionStatuses);
8583

8684
/**
8785
* response body
@@ -102,19 +100,19 @@ public void setComponentKey(String componentKey) {
102100
/**
103101
* Build openapi paths
104102
*
105-
* @param apiConfig Configuration of smart-doc
106-
* @param apiDocList List of API DOC
107-
* @param tags tags
103+
* @param apiConfig Configuration of smart-doc
104+
* @param apiSchema Project API schema
105+
* @param tags tags
108106
* @return Map of paths
109107
*/
110-
public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocList, Set<OpenApiTag> tags) {
108+
public Map<String, Object> buildPaths(ApiConfig apiConfig, ApiSchema<ApiDoc> apiSchema, Set<OpenApiTag> tags) {
111109
Map<String, Object> pathMap = new HashMap<>(500);
112110
Set<ApiMethodDoc> methodDocs = DocMapping.METHOD_DOCS;
113111
for (ApiMethodDoc methodDoc : methodDocs) {
114112
String[] paths = methodDoc.getPath().split(";");
115113
for (String path : paths) {
116114
path = path.trim();
117-
Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc());
115+
Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc(), apiSchema.getApiExceptionStatuses());
118116
if (!pathMap.containsKey(path)) {
119117
pathMap.put(path, request);
120118
} else {
@@ -142,9 +140,9 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocLi
142140
* @param apiDoc ApiDoc
143141
* @return Map of path urls
144142
*/
145-
public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc) {
143+
public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List<ApiExceptionStatus> apiExceptionStatuses) {
146144
Map<String, Object> request = new HashMap<>(4);
147-
request.put(apiMethodDoc.getType().toLowerCase(), buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc));
145+
request.put(apiMethodDoc.getType().toLowerCase(), buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc, apiExceptionStatuses));
148146
return request;
149147
}
150148

@@ -348,11 +346,12 @@ public static Map<String, Object> buildParametersSchema(ApiReqParam header) {
348346
/**
349347
* build response
350348
*
351-
* @param apiMethodDoc ApiMethodDoc
352-
* @param apiConfig ApiConfig
349+
* @param apiMethodDoc ApiMethodDoc
350+
* @param apiConfig ApiConfig
351+
* @param apiExceptionStatuses apiExceptionStatuses
353352
* @return response info
354353
*/
355-
public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc) {
354+
public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, List<ApiExceptionStatus> apiExceptionStatuses) {
356355
Map<String, Object> response = new HashMap<>(10);
357356
response.put("200", buildResponsesBody(apiConfig, apiMethodDoc));
358357
return response;
@@ -457,22 +456,19 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
457456
propertiesData.put("format", "binary");
458457
}
459458
if ("object".equals(apiParam.getType())) {
459+
propertiesData.put("description", apiParam.getDesc() + "(object)");
460460
if (CollectionUtil.isNotEmpty(apiParam.getChildren())) {
461-
propertiesData.put("type", "object");
462-
propertiesData.put("description", apiParam.getDesc() + "(object)");
463461
if (!apiParam.isSelfReferenceLoop()) {
464462
String childSchemaName = OpenApiSchemaUtil.getClassNameFromParams(apiParam.getChildren());
465463
if (childSchemaName.contains(OpenApiSchemaUtil.NO_BODY_PARAM)) {
466464
propertiesData.put("type", "object");
467-
propertiesData.put("description", apiParam.getDesc() + "(object)");
468465
} else {
469466
component.put(childSchemaName, buildProperties(apiParam.getChildren(), component, isResp));
470467
propertiesData.put("$ref", componentKey + childSchemaName);
471468
}
472469
}
473470
} else {
474471
propertiesData.put("type", "object");
475-
propertiesData.put("description", apiParam.getDesc() + "(object)");
476472
}
477473
}
478474
if (apiParam.getExtensions() != null && !apiParam.getExtensions().isEmpty()) {
@@ -482,14 +478,47 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
482478
return propertiesData;
483479
}
484480

481+
/**
482+
* Builds component data for API documentation.
483+
* This method iterates through all API documentation entries to extract request and response parameter information,
484+
* and organizes them into OpenAPI component schemas.
485+
*
486+
* @param apiDocs List of API documentation, containing multiple API method descriptions.
487+
* @return Returns a map containing all component schemas.
488+
*/
489+
public Map<String, Object> buildComponentData(List<ApiDoc> apiDocs) {
490+
Map<String, Object> component = new HashMap<>(16);
491+
component.put(DocGlobalConstants.DEFAULT_PRIMITIVE, STRING_COMPONENT);
492+
apiDocs.forEach(
493+
a -> {
494+
List<ApiMethodDoc> apiMethodDocs = a.getList();
495+
apiMethodDocs.forEach(
496+
method -> {
497+
//request components
498+
String requestSchema = OpenApiSchemaUtil.getClassNameFromParams(method.getRequestParams());
499+
List<ApiParam> requestParams = method.getRequestParams();
500+
Map<String, Object> prop = buildProperties(requestParams, component, false);
501+
component.put(requestSchema, prop);
502+
//response components
503+
List<ApiParam> responseParams = method.getResponseParams();
504+
String responseSchemaName = OpenApiSchemaUtil.getClassNameFromParams(method.getResponseParams());
505+
component.put(responseSchemaName, buildProperties(responseParams, component, true));
506+
}
507+
);
508+
}
509+
);
510+
component.remove(OpenApiSchemaUtil.NO_BODY_PARAM);
511+
return component;
512+
}
513+
485514
/**
486515
* Get a list of OpenAPI's document data
487516
*
488517
* @param config Configuration of smart-doc
489518
* @param projectBuilder JavaDocBuilder of QDox
490519
* @return List of OpenAPI's document data
491520
*/
492-
public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
521+
public ApiSchema<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
493522
config.setShowJavaType(false);
494523
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
495524
builderTemplate.checkAndInit(config, Boolean.TRUE);
@@ -499,4 +528,9 @@ public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectB
499528
Objects.requireNonNull(docBuildTemplate, "doc build template is null");
500529
return docBuildTemplate.getApiData(configBuilder);
501530
}
531+
532+
public static Map<String, Object> buildErrorStatusResponse(ApiConfig apiConfig, List<ApiExceptionStatus> apiExceptionStatuses) {
533+
// TODO
534+
return null;
535+
}
502536
}

0 commit comments

Comments
 (0)