support a per-function @noCbSwagger attribute#43
support a per-function @noCbSwagger attribute#43davidAtInleague wants to merge 2 commits intocoldbox-modules:developmentfrom
@noCbSwagger attribute#43Conversation
the presence of this attribute prevents the inclusion of the function's associated documentation from ending up in swagger docs
jclausen
left a comment
jclausen
left a comment
There was a problem hiding this comment.
Looks great @davidAtInleague ! A couple of cleanup items and then I will merge this a bump a patch.
models/RoutesParser.cfc
Outdated
| } | ||
| } | ||
|
|
||
| if ( path.count() == 0 ) { |
There was a problem hiding this comment.
Use boolean evaluation here, per Ortus Coding Standards
models/RoutesParser.cfc
Outdated
| // then do not expose this function to swagger docs. | ||
| // | ||
| if ( !isNull( arguments.handlerMetadata ) ) { | ||
| var maybeNull_metaData = getFunctionMetadata( handlerMetadata = arguments.handlerMetadata, functionName = lCase( actions[ methodName ] ) ); |
There was a problem hiding this comment.
Just call this var functionMetadata
models/RoutesParser.cfc
Outdated
| * return true if the metadata represents a function marked "noCbSwagger" | ||
| */ | ||
| private boolean function isAnnotatedWithTruthyNoCbSwaggerAttribute( required struct functionMetadata ) { | ||
| if ( !structKeyExists( functionMetadata, "noCbSwagger" ) ) { |
There was a problem hiding this comment.
Let's call this function metadata cbSwagger, check for its existence, and then look for a boolean false. This can open up additional inclusions in the future by using cbSwagger or cbSwagger=true on a function or component. When we implement this, we could then do discovery of an entire site without includes/excludes by simply using the component/function MD
There was a problem hiding this comment.
So your function annotation would become:
function myFunction() cbSwagger=false{...}
or
/**
* @cbswagger false
**/
function myFunction(){...}
models/RoutesParser.cfc
Outdated
| return false; | ||
| } | ||
|
|
||
| if ( trim( functionMetadata.noCbSwagger ) == "" ) { |
There was a problem hiding this comment.
You can simplify the conditionals here with a ternary here:
return !structKeyExists( functionMetadata, "cbSwagger" )
? false
: !functionMetadata.cbswagger.len()
|| (
isValid( "boolean", functionMetadata.noCbSwagger ) && functionMetadata.noCbSwagger
);
models/RoutesParser.cfc
Outdated
| /** | ||
| * return true if the metadata represents a function marked "noCbSwagger" | ||
| */ | ||
| private boolean function isAnnotatedWithTruthyNoCbSwaggerAttribute( required struct functionMetadata ) { |
There was a problem hiding this comment.
Let's rename this method to isCbSwaggerEnabled
There was a problem hiding this comment.
Actually since this is within the scope of the parser, let's just call this isDocumentationEnabled. Then we could hook in to other exclusions, as necessary, down the road.
|
I tried to run cfformat but get the following, I'm not sure what the issue is here: |
3 participants
the presence of this attribute prevents the inclusion of the function's associated documentation from ending up in swagger docs
Description
completes #42
Type of change
Checklist