diff --git a/README.md b/README.md index c62a35a82..1493e4391 100755 --- a/README.md +++ b/README.md @@ -90,6 +90,7 @@ The `executions` block is used to specify the phase of the build lifecycle you w | `operationIdFormat` | Format of `operationId` used in Swagger spec. For historical reasons default is Java method name. Since 3.1.8, for new APIs suggested format is: `{{className}}_{{methodName}}_{{httpMethod}}`. `{{packageName}}` token is also supported. | | `externalDocs` | URL Reference to external documentation | | `responseMessageOverrides` | Default response message overrides of type ```@ApiResponse```. Example: `401Unauthenticated - could not authenticate the user.` | +| `includeHidden` | Specifies whether hidden resources, operations and parameters should be included in the generated output. Default: `false`. | # Template File If you'd like to generate a template-driven static document, such as markdown or HTML documentation, you'll need to specify a [handlebars](https://github.com/jknack/handlebars.java) template file in ```templatePath```. diff --git a/src/main/java/com/github/kongchen/swagger/docgen/AbstractDocumentSource.java b/src/main/java/com/github/kongchen/swagger/docgen/AbstractDocumentSource.java index 0c79c2c95..e6d63293a 100644 --- a/src/main/java/com/github/kongchen/swagger/docgen/AbstractDocumentSource.java +++ b/src/main/java/com/github/kongchen/swagger/docgen/AbstractDocumentSource.java @@ -421,6 +421,7 @@ protected ClassSwaggerReader resolveApiReader() throws GenerateException { reader.setTypesToSkip(this.typesToSkip); reader.setOperationIdFormat(this.apiSource.getOperationIdFormat()); reader.setResponseMessageOverrides(this.apiSource.getResponseMessageOverrides()); + reader.setIncludeHidden(apiSource.isIncludeHidden()); return reader; } else { ClassSwaggerReader customApiReader = getCustomApiReader(customReaderClassName); diff --git a/src/main/java/com/github/kongchen/swagger/docgen/mavenplugin/ApiSource.java b/src/main/java/com/github/kongchen/swagger/docgen/mavenplugin/ApiSource.java index 61f04dfb0..0a31ef843 100644 --- a/src/main/java/com/github/kongchen/swagger/docgen/mavenplugin/ApiSource.java +++ b/src/main/java/com/github/kongchen/swagger/docgen/mavenplugin/ApiSource.java @@ -149,6 +149,9 @@ public class ApiSource { @Parameter private List responseMessageOverrides; + @Parameter + private boolean includeHidden = false; + public Set> getValidClasses(Class clazz) { Set> classes = new LinkedHashSet>(); @@ -500,5 +503,13 @@ public Boolean getRemoveBasePathFromEndpoints() { public void setRemoveBasePathFromEndpoints(Boolean removeBasePathFromEndpoints) { this.removeBasePathFromEndpoints = removeBasePathFromEndpoints; } + + public boolean isIncludeHidden() { + return includeHidden; + } + + public void setIncludeHidden(boolean includeHidden) { + this.includeHidden = includeHidden; + } } diff --git a/src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java b/src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java index 821f6c51e..21eb2c693 100644 --- a/src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java +++ b/src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java @@ -1,6 +1,7 @@ package com.github.kongchen.swagger.docgen.reader; import com.github.kongchen.swagger.docgen.ResponseMessageOverride; +import com.github.kongchen.swagger.docgen.mavenplugin.ApiSource; import com.github.kongchen.swagger.docgen.util.TypeExtracter; import com.github.kongchen.swagger.docgen.util.TypeWithAnnotations; import com.google.common.collect.Lists; @@ -40,6 +41,7 @@ public abstract class AbstractReader { protected Swagger swagger; private Set typesToSkip = new HashSet(); protected List responseMessageOverrides; + protected boolean includeHidden = false; protected String operationIdFormat; @@ -292,6 +294,9 @@ protected void updateOperation(String[] apiConsumes, String[] apiProduces, Map parameterAnnotations) { + if (includeHidden) { + return false; + } for (Annotation parameterAnnotation : parameterAnnotations) { if (parameterAnnotation instanceof ApiParam) { return ((ApiParam) parameterAnnotation).hidden(); @@ -301,6 +306,14 @@ private boolean isApiParamHidden(List parameterAnnotations) { return false; } + protected boolean isApiOperationHidden(ApiOperation apiOperation) { + if (includeHidden) { + return false; + } else { + return apiOperation != null && apiOperation.hidden(); + } + } + private boolean hasValidAnnotations(List parameterAnnotations) { // Because method parameters can contain parameters that are valid, but // not part of the API contract, first check to make sure the parameter @@ -577,5 +590,9 @@ public String getOperationIdFormat() { public void setOperationIdFormat(String operationIdFormat) { this.operationIdFormat = operationIdFormat; } + + public void setIncludeHidden(boolean includeHidden) { + this.includeHidden = includeHidden; + } } diff --git a/src/main/java/com/github/kongchen/swagger/docgen/reader/JaxrsReader.java b/src/main/java/com/github/kongchen/swagger/docgen/reader/JaxrsReader.java index 5810323cb..f4e31dae7 100644 --- a/src/main/java/com/github/kongchen/swagger/docgen/reader/JaxrsReader.java +++ b/src/main/java/com/github/kongchen/swagger/docgen/reader/JaxrsReader.java @@ -93,7 +93,7 @@ public Swagger getSwagger() { } public Swagger read(Class cls) { - return read(cls, "", null, false, new String[0], new String[0], new HashMap(), new ArrayList()); + return read(cls, "", null, includeHidden, new String[0], new String[0], new HashMap(), new ArrayList()); } protected Swagger read(Class cls, String parentPath, String parentMethod, boolean readHidden, String[] parentConsumes, @@ -125,7 +125,7 @@ protected Swagger read(Class cls, String parentPath, String parentMethod, boo List filteredMethods = getFilteredMethods(cls); for (Method method : filteredMethods) { ApiOperation apiOperation = AnnotationUtils.findAnnotation(method, ApiOperation.class); - if (apiOperation != null && apiOperation.hidden()) { + if (isApiOperationHidden(apiOperation)) { continue; } Path methodPath = AnnotationUtils.findAnnotation(method, Path.class); @@ -282,6 +282,7 @@ private void handleSubResource(String[] apiConsumes, String httpMethod, String[] responseClass = apiOperation.response(); } LOGGER.debug("handling sub-resource method " + method.toString() + " -> " + responseClass); + // TODO: Should we use includeHidden instead of true? read(responseClass, operationPath, httpMethod, true, apiConsumes, apiProduces, tags, operation.getParameters()); } } @@ -344,7 +345,7 @@ public Operation parseMethod(String httpMethod, Method method) { Map defaultResponseHeaders = null; if (apiOperation != null) { - if (apiOperation.hidden()) { + if (isApiOperationHidden(apiOperation)) { return null; } if (!apiOperation.nickname().isEmpty()) { diff --git a/src/main/java/com/github/kongchen/swagger/docgen/reader/SpringMvcApiReader.java b/src/main/java/com/github/kongchen/swagger/docgen/reader/SpringMvcApiReader.java index fa3b81669..ccbbce481 100644 --- a/src/main/java/com/github/kongchen/swagger/docgen/reader/SpringMvcApiReader.java +++ b/src/main/java/com/github/kongchen/swagger/docgen/reader/SpringMvcApiReader.java @@ -87,7 +87,7 @@ public Swagger read(SpringResource resource) { if (controller.isAnnotationPresent(Api.class)) { Api api = findMergedAnnotation(controller, Api.class); - if (!canReadApi(false, api)) { + if (!canReadApi(includeHidden, api)) { return swagger; } tags = updateTagsForApi(null, api); @@ -106,7 +106,7 @@ public Swagger read(SpringResource resource) { continue; } ApiOperation apiOperation = findMergedAnnotation(method, ApiOperation.class); - if (apiOperation != null && apiOperation.hidden()) { + if (isApiOperationHidden(apiOperation)) { continue; } @@ -155,7 +155,7 @@ private Operation parseMethod(Method method, RequestMethod requestMethod) { ApiOperation apiOperation = findMergedAnnotation(method, ApiOperation.class); if(apiOperation != null) { - if (apiOperation.hidden()) { + if (isApiOperationHidden(apiOperation)) { return null; } if (!apiOperation.nickname().isEmpty()) {