{"id":26296405,"url":"https://github.com/charliedigital/dn9-openapi-codegen","last_synced_at":"2025-07-16T04:35:16.259Z","repository":{"id":262670637,"uuid":"887966369","full_name":"CharlieDigital/dn9-openapi-codegen","owner":"CharlieDigital","description":"Template for setting up .NET 9 web APIs with OpenAPI with TypeScript client codegen for Vue and React SPAs","archived":false,"fork":false,"pushed_at":"2024-11-15T14:03:15.000Z","size":71,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-15T04:18:15.152Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CharlieDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-11-13T15:31:05.000Z","updated_at":"2025-03-14T08:31:11.000Z","dependencies_parsed_at":"2024-11-15T09:00:53.043Z","dependency_job_id":null,"html_url":"https://github.com/CharlieDigital/dn9-openapi-codegen","commit_stats":null,"previous_names":["charliedigital/dn9-openapi-codegen"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/CharlieDigital/dn9-openapi-codegen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CharlieDigital%2Fdn9-openapi-codegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CharlieDigital%2Fdn9-openapi-codegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CharlieDigital%2Fdn9-openapi-codegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CharlieDigital%2Fdn9-openapi-codegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CharlieDigital","download_url":"https://codeload.github.com/CharlieDigital/dn9-openapi-codegen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CharlieDigital%2Fdn9-openapi-codegen/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265481870,"owners_count":23773966,"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":[],"created_at":"2025-03-15T04:18:17.246Z","updated_at":"2025-07-16T04:35:16.232Z","avatar_url":"https://github.com/CharlieDigital.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# .NET 9 OpenAPI + TypeScript Client Generation\n\nA quick look at .NET 9's new OpenAPI tooling and how it compares to earlier versions of .NET using the `swagger` CLI tool (`Swashbuckle.AspNetCore.Cli`).\n\n\u003e ℹ️ Fork or clone to play with this yourself and explore how it improves/digresses from Swashbuckle CLI\n\nhttps://github.com/user-attachments/assets/805d961d-1d03-4933-b045-92e3bb85ef4a\n\nLayout:\n\n```\n/api-c              Controller API example\n/api                Minimal API example\n/openapi-spec-c     Controller API OpenAPI spec output target\n/openapi-spec       Minimal API OpenAPI spec output target\n/react-spa          React SPA generating a TypeScript client using the /api-c output\n/vue-spa            Vue SPA generating a TypeScript client using the /api output\n```\n\n## Setup the Project\n\n```bash\n# Create the workspace\nmkdir dn9-openapi-codegen\n\n# Create the .NET 9 web app\ndn9-openapi-codgen\ndotnet new webapi -minimal -f net9.0\n\n# Create the SPA (Vue) or your framework of choice\ncd ../\nmkdir vue-spa\ncd vue-spa\nyarn create vite .\n```\n\n\u003e ⚠️ IMPORTANT NOTE: Like the earlier Swashbuckle tooling, this new tooling starts the server to generate the OpenAPI spec.  This means that your startup code will be invoked.  Be aware of this if your startup code requires \"active\" components and replace it with a mock/stub that gets loaded/used when you see a flag (see the next section where we add an environment variable called `GEN` for this purpose to indicate that we are in a code generation context).\n\n## Setup the .NET Web API Project\n\nAdd the following package:\n\n```bash\ndotnet add package Microsoft.Extensions.ApiDescription.Server\n```\n\nNow update the `.csproj` file to include the following:\n\n```xml\n\u003c!--\n  api/api.csproj\n--\u003e\n\u003c!--\n  This property group contains the directives for generating the\n  OpenAPI specification.\n--\u003e\n\u003cPropertyGroup\u003e\n  \u003c!-- The output directory (placed one level up in this case) --\u003e\n  \u003cOpenApiDocumentsDirectory\u003e../openapi-spec\u003c/OpenApiDocumentsDirectory\u003e\n  \u003c!-- The file name --\u003e\n  \u003cOpenApiGenerateDocumentsOptions\u003e--file-name api-spec\u003c/OpenApiGenerateDocumentsOptions\u003e\n\u003c/PropertyGroup\u003e\n```\n\nNow build and verify the `/openapi-spec/api-spec.json` file is created.\n\nFor more details, [see this doc](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-9.0).\n\nNow we can pull these into our front-end projects.\n\n## Configuring the Vue SPA\n\nWe'll use the [Hey API](https://heyapi.dev/) package with Axios.\n\n```bash\ncd vue-spa\nyarn add @hey-api/client-axios \u0026\u0026 yarn add @hey-api/openapi-ts -D\n```\n\nThen update the `package.json` to add our build command.\n\n```json\n// vue-spa/package.json\n\"scripts\": {\n  \"gen\": \"openapi-ts\"\n}\n```\n\nAnd now create a root level file `openapi-ts.config.ts`:\n\n```js\n// vue-spa/openapi-ts.config.ts\nimport { defineConfig } from '@hey-api/openapi-ts';\n\nexport default defineConfig({\n  client: '@hey-api/client-axios',\n  input: '../openapi-spec/api-spec.json',\n  output: 'src/api',\n});\n```\n\nNow we can manually test generate a client\n\n```bash\n# vue-spa\nyarn gen\n```\n\n## Generate on Build\n\nIf we want to generate on build of our .NET project, we need to set up a hook in our `.csproj`\n\n```xml\n\u003c!-- api/api.csproj --\u003e\n\n\u003c!-- This section is a set of post-build commands --\u003e\n\u003cTarget Name=\"GenerateSpec\" AfterTargets=\"Build\" Condition=\"$(Configuration)=='Gen' Or $(GEN)=='true'\"\u003e\n  \u003cMessage Text=\"Generating OpenAPI schema file.\" Importance=\"high\" /\u003e\n\n  \u003c!-- Generate TS bindings for the web app --\u003e\n  \u003cExec Command=\"yarn gen\" WorkingDirectory=\"../vue-spa\" /\u003e\n\u003c/Target\u003e\n```\n\nWe trigger this manually using:\n\n```bash\n# macOS, Linux\nGEN=true dotnet build\n\n# macOS, Linux, Windows\ndotnet build --configuration Gen\n```\n\n(Feel free to remove this constraint if you want it to always generate)\n\nWe can also make this work for hot reloads (see the video at the top):\n\n```bash\n# macOS, Linux\nGEN=true dotnet watch build --non-interactive\n\n# macOS, Linux, Windows\ndotnet watch build --non-interactive --property:Configuration=Gen\n```\n\nFor convenience, you might consider putting this into a script called `_watch.sh`.\n\n## Controller Based APIs\n\nThis also works more or less the same way with controller APIs:\n\n```bash\n# Make a new directory and project with the controller API\nmkdir api-c\ncd api-c\ndotnet new webapi --use-controllers --no-https -f net9.0\n\n# Add the project to the solution (for intellisense)\ncd ../\ndotnet sln add api-c\n```\n\nThis example generates a client for the `react-spa` app.\n\n## Downsides\n\nBig downside from earlier Swagger tooling is that there does not appear to be a way to automatically incorporate the XML document comments into the output schema.\n\nThis is accomplished by [metadata attributes](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-9.0\u0026tabs=minimal-apis).\n\n(Boooooo!)\n\nThis will probably be overcome in time by someone taking the initiative to create [a transformer](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?view=aspnetcore-9.0) that will pull in descriptions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharliedigital%2Fdn9-openapi-codegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharliedigital%2Fdn9-openapi-codegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharliedigital%2Fdn9-openapi-codegen/lists"}