Skip to content

Markdown Documentation

tapik ships a Markdown generator (markdown-docs) that produces a lightweight API reference from your endpoint definitions. This is useful for sharing REST contracts with stakeholders who do not read the Kotlin source.

Output Layout

  • Location: build/generated/API.md
  • Grouping: Endpoints are grouped by package and Kotlin source file. Each group starts with an # heading for the file, followed by ## sections per endpoint.
  • Content:
  • HTTP method and resolved path.
  • Description and details from the DSL.
  • Tables for parameters, headers, and outputs.
  • Body type descriptions including codec names and media types.

Example excerpt:

# ProductEndpoints.kt

## `getProduct`: Fetch product details

`GET /products/{productId}`

Returns localized information when the locale query parameter is supplied.

### URI Parameters
| Name | Type | Position | Required | Default Value |
| --- | --- | --- | --- | --- |
| `productId` | UUID | In Path | true |  |
| `locale` | String | In Query | false | en-US |

### Input Headers
| Name | Type | Value(s) | Required |
| --- | --- | --- | --- |
| `X-Request-Id` | UUID | — | true |

### Outputs
| Description | Headers | Body |
| --- | --- | --- |
| Status: 200 OK | — | `ProductView` named "product" as `application/json` |
| Status: 404 NOT_FOUND | — | `ProblemDetails` named "problem" as `application/json` |

Keeping Documentation Fresh

  • The report updates every time tapikGenerate runs; check it into version control if you track API changes alongside code.
  • Because the generator reads descriptions and details from your DSL, updating KDoc or strings in endpoint declarations immediately reflects in the Markdown file.
  • Unknown codecs or missing media types show up verbatim; add KDoc to the DSL elements if you need richer context.

Customising or Extending

If you need additional formats (HTML, OpenAPI, etc.), use the Markdown generator as a blueprint:

  1. Depend on dev.akif.tapik:common-plugin to reuse metadata types.
  2. Implement TapikGenerator and register a new id.
  3. Traverse HttpEndpointMetadata to produce your desired output. You can start from the source at common-plugin/src/main/kotlin/plugin/MarkdownDocumentationGenerator.kt.

Remember to add your generator to the Gradle DSL via a nested extension or by manually specifying the enabledGeneratorIds set.