0

What's an advisable way of documenting and sharing APIs (e.g. HTTP web-services)?

The requirements are:

  • A Wiki type system in which anyone can edit any page.
  • An easy way to write an API spec so that the styling/formatting is applied automatically, rather than having to manually add the styling for each individual page.

I would use Wordpress, except that it's not really a Wiki system; it's more of a blog engine. I want a nice, clean, structured hierarchy of pages, and the ability to click and edit instantly.

I tried Google Sites, but this also seems to be unsuitable, because it doesn't allow me to create a consistent style for APIs. The only control I have over styling is "themes", which change the look & feel of the whole site, and aren't specific enough.

I found a hosted solution here, but at $499 p/year I'm sure we can do better.

Any suggestions?

Jonathan
  • 32,202
  • 38
  • 137
  • 208
  • 1
    +1. I asked a similar question here: http://stackoverflow.com/questions/3129729/, and never got a satisfactory answer. – Yahel Dec 02 '10 at 02:30

3 Answers3

2

Many projects use trac. Here is an example of a project that uses it http://djangobb.org/wiki

Trac integrates together wiki, issue tracking and source control.

cababunga
  • 3,090
  • 15
  • 23
  • +1 trac, it's great. Although I miss proper mediawiki markup. – El Yobo Dec 02 '10 at 02:44
  • trac would do the job, but I've heard its a bit of a beast in terms of complexity. – Jonathan Dec 02 '10 at 04:16
  • Not sure why would people say so. In my experience it's easy to setup and integrate with Mercurial or Subversion. Usage and administration is very straightforward too. – cababunga Dec 02 '10 at 17:50
0

Might consider using something like doxygen to generate an inital snapshot and then just wikify that.

Tyler Eaves
  • 12,879
  • 1
  • 32
  • 39
  • Would be elegant, but wouldn't work in this particular scenario, because we don't have control over the code for the back-end web-services. We're only developing the front-end of this system. – Jonathan Dec 02 '10 at 02:47
  • Wouldn't need to have the actual backend code necessarily. Could code up stubs in something like python, or some other doxygen compatible language. – Tyler Eaves Dec 02 '10 at 02:57
0

A similar question was posted here also: Wiki solution for APIs documentations?

and I suggested using MindTouch

**jonathan, just saw your comment about trac adding too much complexity. you'll likely find the same with MindTouch, but that's because you're asking for a solution to a specific problem, and the suitable tools available offer much more capabilities (ie complexities)

Community
  • 1
  • 1
GrandVizier
  • 499
  • 7
  • 19