{"id":18073830,"url":"https://github.com/hvuhsg/goapi","last_synced_at":"2025-04-12T05:23:56.801Z","repository":{"id":112644073,"uuid":"601809698","full_name":"hvuhsg/GoAPI","owner":"hvuhsg","description":"GoAPI - A Fast and Easy-to-use Web Framework for Building APIs in Go","archived":false,"fork":false,"pushed_at":"2024-04-19T12:22:05.000Z","size":203,"stargazers_count":85,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T05:56:52.613Z","etag":null,"topics":["api","go","high-performance","http","json","middleware","ngrok","ngrok-tunnel","openapi","openapi3","rest","rest-api","restful","swagger","web","web-framework"],"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/hvuhsg.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":"security.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-02-14T21:41:22.000Z","updated_at":"2024-11-03T00:24:16.000Z","dependencies_parsed_at":"2024-04-19T13:39:39.649Z","dependency_job_id":"d2abb109-d824-4c09-8851-d7bff557326e","html_url":"https://github.com/hvuhsg/GoAPI","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2FGoAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2FGoAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2FGoAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hvuhsg%2FGoAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hvuhsg","download_url":"https://codeload.github.com/hvuhsg/GoAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248520840,"owners_count":21117938,"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","high-performance","http","json","middleware","ngrok","ngrok-tunnel","openapi","openapi3","rest","rest-api","restful","swagger","web","web-framework"],"created_at":"2024-10-31T10:09:22.947Z","updated_at":"2025-04-12T05:23:56.772Z","avatar_url":"https://github.com/hvuhsg.png","language":"Go","readme":"# GoAPI\n\n\u003cp align=\"center\"\u003e\n    \u003cem\u003eA Fast and Easy-to-use Web Framework for Building APIs in Go\u003c/em\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/hvuhsg/GoAPI/actions/workflows/tests.yml\" target=\"_blank\"\u003e\n\t\t\u003cimg src=\"https://github.com/hvuhsg/GoAPI/actions/workflows/tests.yml/badge.svg?branch=main\" alt=\"tests status\"\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://www.standwithus.com/\" target=\"_blank\"\u003e\n\t\t\u003cimg src=\"https://badge.yehoyada.com\" alt=\"Bring Them Home\"\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Documentation**: \u003ca href=\"https://github.com/hvuhsg/GoAPI/README.md\" target=\"_blank\"\u003ehttps://github.com/hvuhsg/GoAPI/README.md\u003c/a\u003e\n\n**Source Code**: \u003ca href=\"https://github.com/hvuhsg/GoAPI\" target=\"_blank\"\u003ehttps://github.com/hvuhsg/GoAPI\u003c/a\u003e\n\n---\n\n\nGoAPI is a web framework written in Go that is inspired by FastAPI. It allows you to quickly build and deploy RESTful APIs with minimal effort. The framework comes with built-in validators that can be used to validate and auto-build the API schema with OpenAPI format (version 3). This means you can focus on the main logic of your application while the framework handles the validation and API documentation generation.  \n\n\nThe key features are:\n- **automatic docs** [----\u003e](#api-documentation)\n- **extensible validators system** [----\u003e](#validation)\n- **high level syntax** [----\u003e](#usage)\n- **middlewares** support [----\u003e](#middlewares)\n- **native handlers** support [----\u003e](#native-handlers)\n- **SSL/TLS** support [----\u003e](#https-support)\n- **ngrok tunnel** built in [----\u003e](#ngrok-tunnel)\n\n## Quick Start\n### Install\nTo install GoAPI, you need to have Go version 1.13 or higher installed on your system. Once you have installed Go, you can use the following command to install GoAPI:\n\n```sh\ngo get github.com/hvuhsg/GoAPI\n```\n\n### Usage\n\nTo use GoAPI, you need to import it in your Go code and create a new instance of the goapi.App object:\n\n```go\npackage main\n\nimport \"github.com/hvuhsg/goapi\"\n\nfunc main() {\n\tapp := goapi.GoAPI(\"small\", \"1.0v\")\n}\n```\n\nOnce you have created the app instance, you can add routes to it by calling the Path() method and specifying the route path. You can also set the HTTP methods that the route supports using the Methods() method. Here is an example of a route that support GET method:\n\n```go\npackage main\n\nimport (\n\t\"github.com/hvuhsg/goapi\"\n\t\"github.com/hvuhsg/goapi/request\"\n\t\"github.com/hvuhsg/goapi/responses\"\n\t\"github.com/hvuhsg/goapi/validators\"\n)\n\nfunc main() {\n\tapp := goapi.GoAPI(\"small\", \"1.0v\")\n\n\techo := app.Path(\"/echo\")\n\techo.Methods(goapi.GET)\n\techo.Description(\"echo a back\")\n\techo.Parameter(\"a\", goapi.QUERY, validators.VRequired{}, validators.VIsInt{})\n\techo.Action(func(request *request.Request) responses.Response {\n\t\treturn responses.NewJSONResponse(responses.Json{\"a\": request.GetInt(\"a\")}, 200)\n\t})\n\n\tapp.Run(\"127.0.0.1\", 8080)\n}\n```\n\nIn the above example, we have created a route at `/echo` that supports GET method. We have also added a description for the route and specified that it expects an integer parameter called \"a\". Finally, we have specified the action that should be performed when the route is accessed. In this case, we are returning a JSON object that contains a \"a\" key with the value of a as an integer.\n\nYou can add as many routes as you like to the app instance, and each route can have its own unique set of parameters and validators.\n\n## Examples\n\nTo help you get started with using GoAPI, we have provided some examples in the examples directory of the repository. These examples demonstrate various use cases of the framework and how to use its features.\n\nThe examples included are:  \n- [**smallest**](/examples/smallest/) The smallest example of ready to run api.\n- [**math_api**](/examples/math_api/) Simple use of methods, parameters and validators.  \n- [**external_handler**](/examples/external_handler/) Use of external handler (FileServer) int the app.\n- [**tls**](/examples/tls/) Running the app with HTTPS support.\n- [**ngrok_tunnel**](/examples/ngrok_tunnel/) Run your app over ngrok tunnel without any external dependencies.  \n\nTo run the examples, navigate to the examples directory and run the following command:\n\n```sh\ngo run \u003cexample_name\u003e/main.go\n```\n\nThis will start the example server `127.0.0.1:8080` and you can visit the example endpoints in your web browser or via curl.\nTo see all of the endpoints tou can visit `127.0.0.1:8080/docs` to see the auto generated interactive docs.\n\nFeel free to use these examples as a starting point for your own projects and modify them as needed.\n\n## Validation\nGoAPI comes with built-in validators that can be used to validate input data automatically. In the above example, we used the `VIsInt` validator to ensure that the \"timestamp\" parameter is an integer. We also used the `VRange` validator to ensure that the \"a\" and \"b\" parameters falls within a specified range.\n\nIf the input data fails validation, the framework will automatically return an error to the client. This means you can focus on the main logic of your application, and the framework will handle the validation for you.\n\nHere is a validator for example\n\u003cdetails\u003e\n\u003csummary\u003eSee validator\u003c/summary\u003e\n\n```go\n// VRange implementaion for refernce\ntype VRange struct {\n\tMin float64\n\tMax float64\n}\n\nfunc (v VRange) UpdateOpenAPISchema(schema *openapi3.Schema) {\n\tschema.Min = \u0026v.Min\n\tschema.Max = \u0026v.Max\n}\nfunc (v VRange) Validate(r *request.Request, paramName string) error {\n\tvr := VIsFloat{}\n\terr := vr.Validate(r, paramName)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfVal := r.GetFloat(paramName)\n\n\tif fVal \u003c v.Min || fVal \u003e v.Max {\n\t\treturn fmt.Errorf(\"parameter %s must be between %f and %f\", paramName, v.Min, v.Max)\n\t}\n\n\treturn nil\n}\n```\n\u003c/details\u003e\n\n## Middlewares\nGoAPI supports middlewares, middlewares can be defind in the app level or in the view level, middlewares in the app level are applied to all views.\n\nhere is an example for logging middleware, that logs requests in the format that nginx uses.\n\u003cdetails\u003e\n\u003csummary\u003eSee middleware\u003c/summary\u003e\n\n```go\ntype LoggingMiddleware struct{}\n\nfunc (LoggingMiddleware) Apply(next AppHandler) AppHandler {\n\treturn func(request *request.Request) responses.Response {\n\t\tresponse := next(request)\n\n\t\tscheme := \"http\"\n\t\tif request.HTTPRequest.TLS != nil {\n\t\t\tscheme = \"https\"\n\t\t}\n\t\tfullURL := fmt.Sprintf(\"%s://%s%s\", scheme, request.HTTPRequest.Host, request.HTTPRequest.URL.String())\n\n\t\tmethod := request.HTTPRequest.Method\n\t\tpath := request.HTTPRequest.URL.Path\n\t\tresponseSize := len(response.ToBytes())\n\t\tremoteAddr := request.HTTPRequest.RemoteAddr\n\t\tdate := time.Now().Format(\"2006-01-02 15:04:05\")\n\t\tuserAgent := request.HTTPRequest.UserAgent()\n\t\tstatusCode := response.StatusCode()\n\n\t\tlog.Printf(\"%s - - [%s] \\\"%s %s %s\\\" %d %d \\\"%s\\\" \\\"%s\\\"\\n\", remoteAddr, date, method, path, request.HTTPRequest.Proto, statusCode, responseSize, fullURL, userAgent)\n\t\treturn response\n\t}\n}\n```\n\u003c/details\u003e\n\nTo apply middlewares simply pass it to the Middlewares method for the app or for the view.\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/hvuhsg/goapi\"\n\t\"github.com/hvuhsg/goapi/middlewares\"\n)\n\nfunc main() {\n\tapp := goapi.GoAPI(\"external handler\", \"1.0v\")\n\tapp.Middlewares(middlewares.LoggingMiddleware{})\n}\n```\n\n## Native handlers\nTo allow the usage of native handlers we added a simple way to include them in the app, simply pass the native Handler into the Include method of the app.\n\nNote that native handlers will not be shown in the automatic docs, and currently will not be affected by the middlewares.\n\nhere is an example:\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/hvuhsg/goapi\"\n)\n\nfunc main() {\n\tapp := goapi.GoAPI(\"external handler\", \"1.0v\")\n\n\t// Serve files from GoAPI app using the Include method that allow us to include external handlers in the app\n\tapp.Include(\"/\", http.FileServer(http.Dir(\".\")))\n\n\tapp.Run(\"127.0.0.1\", 8080)\n}\n```\n\n## API Documentation\nGoAPI can automatically generate API documentation in OpenAPI format (version 3). This makes it easy to share your API with others and integrate it with other tools that support OpenAPI.\n\nTo generate the API documentation, you can simply visit the \"/docs\" endpoint in your web browser. This will display a user-friendly interface that allows you to view the API schema and test the API endpoints.\nFor the JSON schema you can visit \"/openapi.json\".  \n\n\n![Swagger UI](/docs/images/openapi_closed.png)\n![Swagger route open](/docs/images/openapi_open.png)\n\n## HTTPS Support\nGoAPI can also serve the api over https, this is not recommanded for production.\nWe recommand using Nginx or other types of reverse proxy to handle the SSL/TLS security.\n\nTo run the application over TLS just use the **RunTLS** method of the app.\n\n```go\npackage main\n\nimport (\n\t\"github.com/hvuhsg/goapi\"\n\t\"github.com/hvuhsg/goapi/request\"\n\t\"github.com/hvuhsg/goapi/responses\"\n)\n\nfunc main() {\n\tapp := goapi.GoAPI(\"TLS example\", \"1.0v\")\n\n\troot := app.Path(\"/\")\n\troot.Methods(goapi.GET)\n\troot.Description(\"simple route\")\n\troot.Action(func(request *request.Request) responses.Response {\n\t\treturn responses.NewHTMLResponse(\"\u003ch1\u003eHTML Over HTTPS\u003c/h1\u003e\", 200)\n\t})\n\n\tapp.RunTLS(\"127.0.0.1\", 8080, \"./server.crt\", \"./server.key\")\n}\n```\n\n## Ngrok Tunnel\nGoAPI support seamless and simple use of ngrok tunnels during the development of the server.\n\u003cdetails\u003e\n\u003csummary\u003eCode example\u003c/summary\u003e\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\t\"os\"\n\n\t\"github.com/hvuhsg/goapi\"\n\t\"github.com/hvuhsg/goapi/request\"\n\t\"github.com/hvuhsg/goapi/responses\"\n)\n\nfunc main() {\n\tapp := goapi.GoAPI(\"ngrok tunnel\", \"1.0v\")\n\n\techo := app.Path(\"/\")\n\techo.Methods(goapi.GET)\n\techo.Description(\"home page\")\n\techo.Action(func(request *request.Request) responses.Response {\n\t\treturn responses.NewHTMLResponse(\"\u003ch1\u003eServed over ngrok tunnel\u003c/h1\u003e\", 200)\n\t})\n\n\tngrokToken := os.Getenv(\"NGROK_TOKEN\")\n\tif ngrokToken == \"\" {\n\t\tlog.Println(\"Enviroment variable NGROK_TOKEN is required\")\n\t\tos.Exit(1)\n\t}\n\n\tapp.RunNgrok(ngrokToken)\n}\n```\n\u003c/details\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhvuhsg%2Fgoapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhvuhsg%2Fgoapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhvuhsg%2Fgoapi/lists"}