I have a problem making cbSwagger work to document my API project by pulling the resources/apidocs in order to populate the Swagger editor.
a) First, I created resourceful routes in the config/router file (i.e not at the api/v1 module level). As a result, route-visualiser could not find the resourceful routes and handlers under api/v1. However, cbswagger could generate a json file, although as expected, no routes within the api/v1 module could be mapped. They were returned empty to Relax and to the cbSwagger editor.
b) Then, I studied the FluentAPI source code posted recently on GitHub and made the following modifications shown in the attached screens:
First, I moved the resourceful routes from config/Router.cfc to api/v1/config/Router.cfc (see attached screen 1)
Second, I created a resources/apidocs folder where I copied and amended the GitHub examples to suit my API requirements (see attached screen 2)
Third, I created annotations in my handler located at api/v1/handlers/Carriers.cfc (see attached screen 3)
Fourth, I verified cbSwagger module settings in config/coldbox.cfc (see attached screen 4)
Next, I verified that route-visualiser could find all the resourceful routes, which it did, as expected under api/v1 (see attached screen 5)
Finally, I ran cbswagger and got an error (see attached screen 6).
I cannot understand why cbSwagger keeps looking for my handler at “v1.handlers.v1:carriers” instead of simply looking for “v1:carriers” the same way route-visualiser does.
Any explanation would be welcome because I have been struggling with the HMVC-rest template convention for a while, despite closely sticking to the fluentAPI source code shared on GitHub.
When I looked at your Router.cfc, I suspected the “resource” value should be “carriers” (remove “v1:”)
The URI will be /api/v1/carriers
Thanks for the feedback. This is what I did earlier on, meaning defining the resource as “carriers” instead of “v1:carriers” which seems more logical. But two things happened as a result.
1 - In route-visualiser, when I now run the “carriers/” route on line 3, I get an error saying that the “carriers” event does not exist. Although when entered on the URL, api/v1/carriers will display the proper response. In other words, when I open the api/v1 route and run the route carriers/ nested within it, route-visualiser does not pick the complete /api/v1/carriers but only picks up carriers as a route, which indeed triggers an error. This error did not occur when I defined the resource name as v1:carriers.
2 - Now when I run cbswagger, I get yet another error saying that the $ref document defined in resources/apidocs cannot be loaded and parsed. (see attached screen). Could this be due to the syntax used in the handler’s annotation (see the handler’s screen for action index) or in the way I structured the response200 file in the resources/apidocs/api-v1/Carriers/index folder ?
I have attached the following screen printouts to illustrate the issues after the resource name change:
- The error when cbswagger is run
- The responses file in resources/apidocs
Attached is the complete “responses” file.
I still believe that the resource value should be “carriers”, not “v1:carriers”.
I managed to set up a test similar to what you have. I also found out that cbSwagger settings should be placed inside moduleSettings in ColdBox.cfc.
The “$ref document” error is a generic error telling cbSwagger module unable to locate the file or parse it.
I attached screenshots that might help you figuring out your problem.
I think I have the answer for your problem. The @response-200 could not find the JSON file because of incorrect path. In handler carriers, index() should be
@response-200 ~api-v1/carriers/index/responses.json##200
Follow your directory structure where you place responses.json, “resources/apidocs/api-v1/carriers/index”. cbSwagger substitutes “~” with “resources/apidocs” as defined in cbswagger.samplespath setting.
responses.json
`
{
“200”: {
“description”: “Good morning!”
}
}
`
Lastly, remove “v1:” from resource in Router.cfc as I mentioned before.
Finally got it! Thanks for your help. The issue was with cbSwagger module settings in config/coldbox.cfc. You were right: it seems that the “samplesPath” : “resources/apidocs” would not work in Coldbox 5.6.2. I Simply had to modify the handlers’ annotations with the full path such as: “resources/apidocs/api-v1/carriers/index/responses.json##200” instead of “~/api-v1/carriers/index/responses.json##200”. Attached are the screenshots for Relax and SwaggerEditor successfully pulling the API routes.
Philippe
Beautiful!
“~/api-v1/carriers/index/responses.json##200” should be “~api-v1/carriers/index/responses.json##200”. No forward-slash after the tilde (~).
