{"id":19608598,"url":"https://github.com/teamwork/kommentaar","last_synced_at":"2025-04-27T20:32:58.086Z","repository":{"id":30163478,"uuid":"123177964","full_name":"Teamwork/kommentaar","owner":"Teamwork","description":"Generate documentation for Go APIs","archived":false,"fork":false,"pushed_at":"2025-03-04T19:23:12.000Z","size":9007,"stargazers_count":34,"open_issues_count":7,"forks_count":6,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-04-05T03:13:01.859Z","etag":null,"topics":["documentation","go","openapi"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Teamwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-27T19:33:03.000Z","updated_at":"2025-03-04T19:21:57.000Z","dependencies_parsed_at":"2024-01-17T15:26:43.735Z","dependency_job_id":"b952389c-9d57-43c8-aa7c-05de0bde0009","html_url":"https://github.com/Teamwork/kommentaar","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teamwork%2Fkommentaar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teamwork%2Fkommentaar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teamwork%2Fkommentaar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Teamwork%2Fkommentaar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Teamwork","download_url":"https://codeload.github.com/Teamwork/kommentaar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251204680,"owners_count":21552266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","go","openapi"],"created_at":"2024-11-11T10:15:53.253Z","updated_at":"2025-04-27T20:32:58.066Z","avatar_url":"https://github.com/Teamwork.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GoDoc](https://godoc.org/github.com/teamwork/kommentaar?status.svg)](https://godoc.org/github.com/teamwork/kommentaar)\n![Build Status](https://github.com/teamwork/kommentaar/actions/workflows/go.yml/badge.svg?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/Teamwork/kommentaar/badge.svg?branch=master)](https://coveralls.io/github/Teamwork/kommentaar)\n\nKommentaar generates documentation for Go APIs.\n\nThe primary focus is currently on [OpenAPI](https://github.com/OAI/OpenAPI-Specification)\noutput (previously known as Swagger), but it can also output directly to HTML,\nand the design allows easy addition of other output formats.\n\nGoals:\n\n- Easy to use.\n- Good performance.\n- Will not require significant code refactors to use in almost all cases.\n- Impossible to produce invalid OpenAPI files; prefer being strict over\n  flexible.\n\nNon-goals:\n\n- Support every single last OpenAPI feature. Some features, such as different\n  return values with `anyOf`, don't map well to how Go works, and supporting it\n  would add much complexity and would benefit only a few users.\n\nUsing the tool\n--------------\n\nInstall it:\n\n    $ go get github.com/teamwork/kommentaar\n\nParse one package:\n\n    $ kommentaar github.com/teamwork/desk/api/v1/inboxController\n\nOr several packages:\n\n    $ kommentaar github.com/teamwork/desk/api/...\n\nThe default output is as an OpenAPI 2 YAML file. You can generate a HTML page\nwith `-output html`, or directly serve it with `-output html -serve :8080`. When\nserving the documentation it will rescan the source tree on every page load,\nmaking development/proofreading easier.\n\nSee `kommentaar -h` for the full list of options.\n\nYou can also the [Go API](https://godoc.org/github.com/teamwork/kommentaar), for\nexample to serve documentation in an HTTP endpoint.\n\n### Usage with Docker\n\n\nThere is a kommentaar Docker image available at `ghcr.io/teamwork/kommentaar` which in some cases may simplify the setup process.\nIt takes in the following parameters:\n\n- `MODULE_PATH` env var (required) - path to your module, e.g. `github.com/teamwork/amazingapp`\n- `EXEC_PATH` env var (optional) - path passed to kommentaar - can be relative or absolute, e.g. `./api/v3/...`, or `/go/src/github.com/teamwork/amazingapp/api/v3/...`. Default value is `/go/src/$MODULE_PATH/...`\n- `CONFIG_NAME` env var (optional) - name of kommentaar config file in the `/config` volume (see below). Default value is `kommentaar.conf`\n- `/code` volume (required) - folder containing your go code\n- `/config` volume (optional) - folder containing your kommentaar config file, by default the included `config.example` file is copied there as `kommentaar.conf`\n- `/output` volume (required) - folder where the generated `swagger.yaml` file will be placed.\n\nUsage examples:\n- `docker run --rm -it -e MODULE_PATH=\"github.com/teamwork/amazingapp\" -v .:/code -v .:/config -v .:/output ghcr.io/teamwork/kommentaar`\n  - This assumes you are running the command in `amazingapp` folder\n  - This is roughly equivalent to `kommentaar -config ./kommentaar.conf github.com/teamwork/amazingapp... \u003e ./swagger.yaml`\n- `docker run --rm -it -e MODULE_PATH=\"github.com/teamwork/amazingapp\" -e EXEC_PATH=\"./api/v3/controller/...\" -e CONFIG_NAME=\".kommentaar.v3\" -v $HOME/dev/amazingapp:/code -v $HOME/dev/amazingapp/config:/config -v %HOME/dev/amazingapp/api/v3:/output ghcr.io/teamwork/kommentaar`\n  - This will run the equivalent of `kommentaar -config $HOME/dev/amazingapp/config/.kommentaar.v3 $GOPATH/src/github.com/teamwork/amazingapp/api/v3/controller/... \u003e $HOME/dev/amazingapp/api/v3/swagger.yaml`\n\n\nSyntax\n------\n\nSee [`doc/syntax.markdown`](doc/syntax.markdown) for a full description of the\nsyntax; a basic example:\n\n```go\ntype bikeRequest struct {\n\t// Frame colour {enum: black red blue, default: black}.\n\tColor string\n\n\t// Frame size in centimetres {required, range: 40-62}.\n\tSize int\n}\n\ntype bikeResponse struct {\n\t// Price in Eurocents.\n\tPrice int\n\n\t// Estimated delivery date {date}.\n\tDeliveryTime int\n}\n\ntype errorResponse struct {\n\tError []string `json:\"errors\"`\n}\n\n// POST /bike/{id} bikes\n// Order a new bike.\n//\n// A more detailed multi-line description.\n//\n// Request body: bikeRequest\n// Response 200: bikeResponse\n// Response 400: errorResonse\n```\n\nConfiguration\n-------------\n\nKommentaar can be configured with a configuration file; see\n[`config.example`](config.example) for the documentation.\n\nRunning Tests\n-------------\n\n`GO111MODULE=off go test ./...`\n\nMotivation and rationale\n------------------------\n\nThe motivation for writing Kommentaar was a lack of satisfaction with existing\ntools:\n\n- [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) requires extensive\n  comments; you will need to duplicate every parameter as `@param foo query\n  string Some description`. It's flexible but also tedious and ugly.\n\n- We implemented [go-swagger](https://github.com/go-swagger/go-swagger) but\n  found several pain points:\n\n  - Implementing it meant doing a significant rewrite of our code base and a lot\n\tof \"glue code\", which made the code uglier in the opinion of many\n\tdevelopers.\n  - Slow; about 30 seconds for a fairly limited amount of endpoints (Kommentaar\n\ttakes about 1.5 seconds for the same).\n  - Very easy to generate invalid OpenAPI files.\n  - Complex codebase made it hard to figure out why it was doing what it was\n\tdoing.\n\n- [goa](https://github.com/goadesign/goa) means a complete rewrite of our API,\n  and whether the goa DSL approach is a good one is also debatable (we haven't\n  tried it due to the prohibitive costs of the rewrite, so lack direct\n  experience).\n\nWe tried implementing both yvasiyarov/swagger and go-swagger, and both ended in\nfairly dismal (and time-consuming) failure.\n\nKommentaar is designed to strike a reasonable balance:\n\n- You will need to duplicate *some* information from the code in comments, but\n  not too much, and it shouldn't have to be updated very often; adding new\n  request or response parameters is still easy.\n\n- Makes *some* assumptions about your code (e.g. that you're returning a\n  `struct`), but not many, and rewriting existing code (e.g. handlers returning\n  a `map[string]interface{}`) should be straightforward.\n\n- Syntax is straightforward and easy to read and write.\n\n- Impossible to make Kommentaar output invalid OpenAPI files (if it does, then\n  that's a bug); the syntax doesn't offer too much flexibility, and the tool\n  errors out when it encounters unexpected or wrong input.\n\n- Reasonably fast and should not exceed more than 2 or 3 seconds for\n  moderate-sized APIs (and it can probably be made faster with some effort).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteamwork%2Fkommentaar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteamwork%2Fkommentaar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteamwork%2Fkommentaar/lists"}