Taffy
Taffy copied to clipboard
atuttle
Providing Additional Documentation to API Consumers
I'm working on writing documentation for the users of my API regarding how to authenticate, who to contact for support, etc., and was trying to figure out how I could wrap that up into Taffy directly instead of editing the dashboard/docs.cfm file.
If I wanted to add a call to an include in the docs.cfm file, that pointed to a user-created file containing all of this text to display for documentation, where would I place that new file with all of my documentation?
I considered putting it in the root of my API site, at the same level as the Taffy directory, but then that document would not be part of the package that's downloaded by new Taffy users.
I considered placing it in the resources directory, but it's not a proper REST resource, so that doesn't make sense either.
How do you think this should be handled? This is how I have it implemented right now, but I don't like that the file required to make it work would not be part of the base Taffy distribution, or that embedding it directly in docs.cfm would require editing core Taffy files to make it work.
What about wrapping your include in <cfif fileExists('../../documentation.cfm')></cfif>?
We should also be careful to support not having Taffy in the web root, because I am fairly certain it works even with a global mapping to the taffy folder right now. If need be, we can make use of the guessResourcesPath() method, or build something like it, to find the api root even if it's not in the web root.
Yeah, I considered the fileExists check as well, and that would definitely work for my particular situation. I'll see if I can come up with a more elegant solution, potentially even creating an additional documentation config variable to define the location of your documentation.
Too much config is a bad thing. Part of what makes Taffy great is strict conventions that work well. If one way can serve all needs, just make it a convention. :)
I agree completely :-). I’ll see what I can come up with.
On Thu, Aug 28, 2014 at 12:11 PM, Adam Tuttle [email protected] wrote:
Too much config is a bad thing. Part of what makes Taffy great is strict conventions that work well. If one way can serve all needs, just make it a convention. :)
Reply to this email directly or view it on GitHub: https://github.com/atuttle/Taffy/issues/223#issuecomment-53757906
Hi Dan. I'm hoping to put out a new version in the next couple of weeks/months. What's your status on this? You'll probably have some upstream commits that you need to merge/rebase-onto.
I'll check tomorrow. Dealing with a kidney stone today :-). Thanks for checking with me.
Dan On Fri, May 29, 2015 at 6:12 PM Adam Tuttle [email protected] wrote:
Hi Dan. I'm hoping to put out a new version in the next couple of weeks/months. What's your status on this? You'll probably have some upstream commits that you need to merge/rebase-onto.
— Reply to this email directly or view it on GitHub https://github.com/atuttle/Taffy/issues/223#issuecomment-106956063.