Is there a way to manage public API documentation?

Question

I have created a custom module for my site that includes a public REST API. We've also written public documentation for the API. It's currently written in Markdown for convenience and easy export. We maintain the documentation in version control so that it stays up-to-date along with changes to the endpoint in the module itself.

We would like to publish this documentation to the site in a way that is publicly accessible. I've found documentation on hook_help but that seems to be targeted towards site admins (e.g. documenting settings for the module). Instead, we're looking to document the API endpoint for an end user. We know we could simply create Page content to hold the documentation but we were looking for something more automatic when the module code is updated.

Is hook_help still the right way to add this content to the site? Is there a way to make only portions of the Help section public? Or is there another way to publish API documentation as part of the module?

We are currently on Drupal 7 if it is relevant.

EDIT:

Additional Info:

• We are using the Services module to manage the API endpoint(s)
• We are less looking for documentation generation and more looking for a way to publish the documentation that we have already written in a way that it is updated automatically when the module is updated. We maintain our documentation in version control so that it is updated as part of development. By doing it manually, it is more comprehensive and directly useful than generated documentation (IMO). We would just like the work done during development to be displayed publicly without having to do the extra step of copy-pasting to a Page (a step which is easily forgotten).

Answer 1

So far as I know for community driven modules only the Services module has support to autogenerate API documentation via the Services Documention module. If you've been the D7 public API without using Services ... then you may be out of luck.

The Services Documentation module generates API documentation for your site’s Services resources. Most of the documentation is generated automatically, using the resource information provided by Services. However, this module provides you with the ability to easily extend that documentation.

We make the following assumptions about your usage of the Services module:

• You are providing an API to a third party, which allows them to access your data via Services.
• You would like to provide a page to API consumers that documents your API endpoints, resources, etc.

Documentation will be made available on your Drupal site at /developers. It will be organized by API version (arbitrarily defined by you), and subsequently displayed hierarchically according to resource, method type, method name, arguments, etc.

Answer 2

One solution you should look at is the combination of RAML and publishing via Hitch.

While it would require you to create a new RAML from scratch (AFAIK there are no generators for Drupal) you get a lot of advantages when using RAML including:

1. Ability to generate a test suite.
2. Parsers allow you to generate stubs or test changes really easily.
3. You can publish PDF/HTML versions of your documentation using tools such as raml2pdf and raml2md.
4. You can use schemas to validate your examples and ensure internal consistency.
5. RAML 1.0 is pretty expressive and you can generate internal templates and use things like inheritance to make building RAML files fairly straight-forward and less time consuming.

As an example, it's possible to define "types":

types:
  BaseObject:
    description: A base object.
    type: object
    properties:
      id: number
      created: number
      update: number

  AnotherType:
    type: BaseObject
    properties:
      new_property: string

Then within your RAML file you can say that a certain type of request accepts an AnotherType or returns AnotherType[].

Once you've got a RAML file, you can then upload it to something like Hitch which can post updates to interested parties and helps spread the word about your services.

Yes, this would require extra-Drupal resources and time, but in my experience this has been worth it.