{"id":15647882,"url":"https://github.com/jakecoffman/crud","last_synced_at":"2025-05-05T22:21:40.122Z","repository":{"id":38326386,"uuid":"341327617","full_name":"jakecoffman/crud","owner":"jakecoffman","description":"OpenAPI v2 builder and input validation for Go APIs, with Swagger UI","archived":false,"fork":false,"pushed_at":"2024-11-02T01:13:53.000Z","size":310,"stargazers_count":43,"open_issues_count":1,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T00:13:50.755Z","etag":null,"topics":["api","go","golang","openapi","rest","rest-api","server","swagger","swagger-ui","validation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jakecoffman.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":"2021-02-22T20:25:43.000Z","updated_at":"2024-11-01T14:54:30.000Z","dependencies_parsed_at":"2024-06-19T00:04:44.479Z","dependency_job_id":"0a59458c-cbea-4d94-8810-8ec1770e2c27","html_url":"https://github.com/jakecoffman/crud","commit_stats":{"total_commits":124,"total_committers":5,"mean_commits":24.8,"dds":"0.16935483870967738","last_synced_commit":"f19df8fcf1fade2a026640b3fd8a69806c805848"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakecoffman%2Fcrud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakecoffman%2Fcrud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakecoffman%2Fcrud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakecoffman%2Fcrud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakecoffman","download_url":"https://codeload.github.com/jakecoffman/crud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252584578,"owners_count":21771986,"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":["api","go","golang","openapi","rest","rest-api","server","swagger","swagger-ui","validation"],"created_at":"2024-10-03T12:21:49.245Z","updated_at":"2025-05-05T22:21:40.107Z","avatar_url":"https://github.com/jakecoffman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## crud\n\n[![GoDoc](https://godoc.org/github.com/jakecoffman/crud?status.svg)](https://godoc.org/github.com/jakecoffman/crud)\n[![Go](https://github.com/jakecoffman/crud/actions/workflows/go.yml/badge.svg)](https://github.com/jakecoffman/crud/actions/workflows/go.yml)\n\nAn OpenAPI v2 builder and validation library for building HTTP/REST APIs.\n\nNo additional dependencies besides the router you choose.\n\n### Status\n\nVersion 1.0 is stable, version 2 will support OpenAPI v3.\n\n### Why\n\nOpenAPI is great, but up until now your options to use it are:\n\n1. Write YAML by hand and then make your server match your spec.\n2. Write YAML by hand and generate your server.\n3. Generate YAML from comments in your code.\n\nNone of these options seems like a great idea.\n\nThis project takes another approach: make a specification in Go code using type-safe builders where possible. The OpenAPI spec is generated from this and validation is done before your handler gets called. \n\nThis reduces boilerplate that you have to write and gives you nice documentation too!\n\n### Examples\n\n- [ServeMux Example](_example/main.go)\n- [Gin-Gonic Example](adapters/gin-adapter/example)\n- [Echo Example](adapters/echo-adapter/example)\n- [Gorilla Mux Example](adapters/gorilla-adapter/example)\n\n### Getting started\n\nCheck the example directory under the adapters for a simple example.\n\nStart by getting the package `go get github.com/jakecoffman/crud`\n\nThen in your `main.go`:\n\n1. Create a router with `NewRouter`, use an adapter from the `adapters` sub-package or write you own.\n2. Add routes with `Add`.\n3. Then call `Serve`.\n\nRoutes are specifications that look like this:\n\n```go\ncrud.Spec{\n\tMethod:      \"PATCH\",\n\tPath:        \"/widgets/{id}\",\n\tPreHandlers: Auth,\n\tHandler:     CreateHandler,\n\tDescription: \"Adds a widget\",\n\tTags:        []string{\"Widgets\"},\n\tValidate: crud.Validate{\n\t\tPath: crud.Object(map[string]crud.Field{\n\t\t\t\"id\": crud.Number().Required().Description(\"ID of the widget\"),\n\t\t}),\n\t\tBody: crud.Object(map[string]crud.Field{\n\t\t\t\"owner\": crud.String().Required().Example(\"Bob\").Description(\"Widget owner's name\"),\n\t\t\t\"quantity\": crud.Integer().Min(1).Default(1).Description(\"The amount requested\")\n\t\t}),\n\t},\n}\n```\n\nThis will add a route `/widgets/:id` that responds to the PATCH method. It generates swagger and serves it at the root of the web application. It validates that the ID in the path is a number, so you don't have to. It also validates that the body is an object and has an \"owner\" property that is a string, again so you won't have to.\n\nIt mounts the swagger-ui at `/` and loads up the generated swagger.json:\n\n![screenshot](/screenshot.png?raw=true \"Swagger\")\n\nThe `PreHandlers` run before validation, and the `Handler` runs after validation is successful.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakecoffman%2Fcrud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakecoffman%2Fcrud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakecoffman%2Fcrud/lists"}