{"id":23160615,"url":"https://github.com/disruptek/openapi","last_synced_at":"2025-05-01T09:16:54.798Z","repository":{"id":45740038,"uuid":"197986931","full_name":"disruptek/openapi","owner":"disruptek","description":"OpenAPI Code Generator for Nim","archived":false,"fork":false,"pushed_at":"2024-08-09T14:40:43.000Z","size":257,"stargazers_count":64,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-01T09:16:49.910Z","etag":null,"topics":["api","client","http","json","nim","openapi","rest","yaml"],"latest_commit_sha":null,"homepage":"","language":"Nim","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/disruptek.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":"2019-07-20T22:29:35.000Z","updated_at":"2024-09-12T13:19:50.000Z","dependencies_parsed_at":"2024-12-17T23:11:37.586Z","dependency_job_id":"0499a8f5-aed7-4754-acbe-aed6e819fcd4","html_url":"https://github.com/disruptek/openapi","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/disruptek%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/disruptek%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/disruptek%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/disruptek%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/disruptek","download_url":"https://codeload.github.com/disruptek/openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251850182,"owners_count":21653978,"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","client","http","json","nim","openapi","rest","yaml"],"created_at":"2024-12-17T23:11:30.389Z","updated_at":"2025-05-01T09:16:54.775Z","avatar_url":"https://github.com/disruptek.png","language":"Nim","readme":"# openapi\n[![Test Matrix](https://github.com/disruptek/openapi/workflows/CI/badge.svg)](https://github.com/disruptek/openapi/actions?query=workflow%3ACI)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/disruptek/openapi?style=flat)](https://github.com/disruptek/openapi/releases/latest)\n![Minimum supported Nim version](https://img.shields.io/badge/nim-1.6.11%2B-informational?style=flat\u0026logo=nim)\n[![License](https://img.shields.io/github/license/disruptek/openapi?style=flat)](#license)\n\n## Example\n\nFirst, you need to convert your YAML swagger input into JSON:\n\n```bash\n$ yq . fungenerators.com/lottery/1.5/swagger.yaml \u003e input.json\n```\n\nYou can render the API every time you build you project, or you can build it via a separate source input.  Either way, it looks the same:\n\n```nim\nimport asyncdispatch\nimport httpclient\nimport httpcore\n\nimport openapi/codegen\n\n# 0) API handle, 1) input JSON source, 2) output Nim source\ngenerate myAPI, \"input.json\", \"output.nim\":\n  ## here you can mess with the generator directly as needed...\n\n  # add a constant from the input to the API...\n  let service = generator.js[\"info\"][\"x-serviceName\"].getStr\n  generator.ast.add newConstStmt(ident\"myService\", newStrLitNode(service))\n\nrender myAPI:\n  ## whatever you write here will be included in your API verbatim\n  echo \"service \" \u0026 myService \u0026 \" loaded\"\n\n  # we might want to rewrite the path (for a particular call) for all\n  # clients of the API we're generating.  easy.\n  getLotteryDraw.base = \"/v2/\"\n\n# use the API...\n\n# maybe we want to change the server for this call in order to test or migrate\n# something, but only for this particular client app.  again, easy.\ngetLotteryCountries.host = \"some.other.host.tld\"\n\nlet\n  request = getLotteryCountries.call()\n  response = waitFor request.issueRequest()\nif response.code.is2xx:\n  echo waitFor response.body\nelse:\n  echo \"failure: \" \u0026 $response.code\n```\n\n## Theory\n\n### Why output Nim source at all?\n\n1. Parsing the API schema and generating the code isn't terribly fast when performed at compile-time, so saving the source allows us to cache that work product to dramatically speed up compilation of an application which actually uses the resultant API and is likely being recompiled more often than the API schema is changing.\n\n1. Eventually, this library will, by default, generate an API which has no third-party module requirements.  We aren't quite there yet, simply because we provide some minor quality-of-life shimming of the HTTP client.\n\n1. Without source text, many forms of tooling (documentation, editor plug-ins, etc.) have needless hoops to jump through, if they work at all.\n\n1. Adding generated code to source control lets us keep track of changes there which are no less critical than changes we might otherwise introduce manually elsewhere.\n\n### Why is the resultant API so noisy?\n\nThe quality of OpenAPI definitions in the wild appears to vary, uh, wildly.  This code attempts to progressively define greater support for the API it receives as input whenever possible.  Hindrances to this goal include name clashes, invalid `$ref`erences, unspecified types, invalid identifiers, ambiguous schemas, and so on.\n\nOur approach is to try to provide the most natural interface possible for the largest portion of the API we can.\n\nYou get a type defined per each operation defined in the API, and an exported instance of that type which is named according to the API's `operationId` specification.  These types allow you to perform trivial overrides or recomposition of generated values such as the `host` and `basePath`, or provide your own tweaks input validation and URL generation procedures.\n\n## Requests\nThe `call` procedure returns a `Recallable` object which holds details associated with a request which may be reissued.  This proc comes in two flavors:\n\nJSON objects matching the OpenAPI parameter locations:\n```nim\nproc call*(call_745068: Call_GetLotteryDraw_745063;\n           path: JsonNode; query: JsonNode; header: JsonNode; formData: JsonNode; body: JsonNode): Recallable\n```\nNamed arguments in native Nim types with default values if supported:\n```nim\nproc call*(call_745069: Call_GetLotteryDraw_745063; game: string; count: int = 0): Recallable\n```\nIn any case, the inputs will be validated according to the API definition and only inputs which match parameters defined by the API will be sent to the server, and only if their types are correct.\n\n## Compile-Time Defines\n\n- `openapiOmitAllDocs` does what it says on the tin; the Nim output API will not\ninclude documentation comments for Json input API calls.\n\n## Some useful links\n- APIs we consume https://github.com/APIs-guru/openapi-directory/blob/master/APIs\n- Schema v2 https://swagger.io/specification/v2\n- Schema v3 https://swagger.io/specification (not yet supported)\n- Amazon Web Services APIs in Nim https://github.com/disruptek/atoz\n- Google Cloud Platform APIs in Nim https://github.com/disruptek/gcplat\n- Microsoft Azure Cloud APIs in Nim https://github.com/disruptek/bluu\n\n## Documentation\nSee [the documentation for the openapi module](https://disruptek.github.io/openapi/openapi.html) as generated directly from the source.\n\n## License\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdisruptek%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdisruptek%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdisruptek%2Fopenapi/lists"}