├── .gitignore
├── .vscode
├── launch.json
└── tasks.json
├── LICENSE
├── README.md
├── api
├── .config
│ └── dotnet-tools.json
├── Controllers
│ └── WeatherForecastController.cs
├── Program.cs
├── Properties
│ └── launchSettings.json
├── WeatherForecast.cs
├── api.csproj
├── appsettings.Development.json
└── appsettings.json
├── vetur.config.js
├── web-vue
├── .gitignore
├── .vscode
│ └── extensions.json
├── README.md
├── index.html
├── package.json
├── public
│ └── favicon.ico
├── src
│ ├── App.vue
│ ├── assets
│ │ └── logo.png
│ ├── components
│ │ └── HelloWorld.vue
│ ├── env.d.ts
│ └── main.ts
├── tsconfig.json
├── vite.config.ts
└── yarn.lock
└── web
├── .gitignore
├── README.md
├── index.html
├── package.json
├── public
└── favicon.ico
├── references
├── codegen
│ ├── .gitkeep
│ ├── core
│ │ ├── ApiError.ts
│ │ ├── ApiRequestOptions.ts
│ │ ├── ApiResult.ts
│ │ ├── CancelablePromise.ts
│ │ ├── OpenAPI.ts
│ │ └── request.ts
│ ├── index.ts
│ ├── models
│ │ └── WeatherForecast.ts
│ └── services
│ │ └── WeatherForecastService.ts
├── swagger.json
└── swagger.yaml
├── src
├── App.svelte
├── assets
│ └── svelte.png
├── lib
│ └── Counter.svelte
├── main.ts
└── vite-env.d.ts
├── svelte.config.js
├── tsconfig.json
├── vite.config.js
└── yarn.lock
/.gitignore:
--------------------------------------------------------------------------------
1 | ## Ignore Visual Studio temporary files, build results, and
2 | ## files generated by popular Visual Studio add-ons.
3 | ##
4 | ## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
5 |
6 | # User-specific files
7 | *.rsuser
8 | *.suo
9 | *.user
10 | *.userosscache
11 | *.sln.docstates
12 |
13 | # User-specific files (MonoDevelop/Xamarin Studio)
14 | *.userprefs
15 |
16 | # Mono auto generated files
17 | mono_crash.*
18 |
19 | # Build results
20 | [Dd]ebug/
21 | [Dd]ebugPublic/
22 | [Rr]elease/
23 | [Rr]eleases/
24 | x64/
25 | x86/
26 | [Aa][Rr][Mm]/
27 | [Aa][Rr][Mm]64/
28 | bld/
29 | [Bb]in/
30 | [Oo]bj/
31 | [Ll]og/
32 | [Ll]ogs/
33 |
34 | # Visual Studio 2015/2017 cache/options directory
35 | .vs/
36 | # Uncomment if you have tasks that create the project's static files in wwwroot
37 | #wwwroot/
38 |
39 | # Visual Studio 2017 auto generated files
40 | Generated\ Files/
41 |
42 | # MSTest test Results
43 | [Tt]est[Rr]esult*/
44 | [Bb]uild[Ll]og.*
45 |
46 | # NUnit
47 | *.VisualState.xml
48 | TestResult.xml
49 | nunit-*.xml
50 |
51 | # Build Results of an ATL Project
52 | [Dd]ebugPS/
53 | [Rr]eleasePS/
54 | dlldata.c
55 |
56 | # Benchmark Results
57 | BenchmarkDotNet.Artifacts/
58 |
59 | # .NET Core
60 | project.lock.json
61 | project.fragment.lock.json
62 | artifacts/
63 |
64 | # StyleCop
65 | StyleCopReport.xml
66 |
67 | # Files built by Visual Studio
68 | *_i.c
69 | *_p.c
70 | *_h.h
71 | *.ilk
72 | *.meta
73 | *.obj
74 | *.iobj
75 | *.pch
76 | *.pdb
77 | *.ipdb
78 | *.pgc
79 | *.pgd
80 | *.rsp
81 | *.sbr
82 | *.tlb
83 | *.tli
84 | *.tlh
85 | *.tmp
86 | *.tmp_proj
87 | *_wpftmp.csproj
88 | *.log
89 | *.vspscc
90 | *.vssscc
91 | .builds
92 | *.pidb
93 | *.svclog
94 | *.scc
95 |
96 | # Chutzpah Test files
97 | _Chutzpah*
98 |
99 | # Visual C++ cache files
100 | ipch/
101 | *.aps
102 | *.ncb
103 | *.opendb
104 | *.opensdf
105 | *.sdf
106 | *.cachefile
107 | *.VC.db
108 | *.VC.VC.opendb
109 |
110 | # Visual Studio profiler
111 | *.psess
112 | *.vsp
113 | *.vspx
114 | *.sap
115 |
116 | # Visual Studio Trace Files
117 | *.e2e
118 |
119 | # TFS 2012 Local Workspace
120 | $tf/
121 |
122 | # Guidance Automation Toolkit
123 | *.gpState
124 |
125 | # ReSharper is a .NET coding add-in
126 | _ReSharper*/
127 | *.[Rr]e[Ss]harper
128 | *.DotSettings.user
129 |
130 | # TeamCity is a build add-in
131 | _TeamCity*
132 |
133 | # DotCover is a Code Coverage Tool
134 | *.dotCover
135 |
136 | # AxoCover is a Code Coverage Tool
137 | .axoCover/*
138 | !.axoCover/settings.json
139 |
140 | # Visual Studio code coverage results
141 | *.coverage
142 | *.coveragexml
143 |
144 | # NCrunch
145 | _NCrunch_*
146 | .*crunch*.local.xml
147 | nCrunchTemp_*
148 |
149 | # MightyMoose
150 | *.mm.*
151 | AutoTest.Net/
152 |
153 | # Web workbench (sass)
154 | .sass-cache/
155 |
156 | # Installshield output folder
157 | [Ee]xpress/
158 |
159 | # DocProject is a documentation generator add-in
160 | DocProject/buildhelp/
161 | DocProject/Help/*.HxT
162 | DocProject/Help/*.HxC
163 | DocProject/Help/*.hhc
164 | DocProject/Help/*.hhk
165 | DocProject/Help/*.hhp
166 | DocProject/Help/Html2
167 | DocProject/Help/html
168 |
169 | # Click-Once directory
170 | publish/
171 |
172 | # Publish Web Output
173 | *.[Pp]ublish.xml
174 | *.azurePubxml
175 | # Note: Comment the next line if you want to checkin your web deploy settings,
176 | # but database connection strings (with potential passwords) will be unencrypted
177 | *.pubxml
178 | *.publishproj
179 |
180 | # Microsoft Azure Web App publish settings. Comment the next line if you want to
181 | # checkin your Azure Web App publish settings, but sensitive information contained
182 | # in these scripts will be unencrypted
183 | PublishScripts/
184 |
185 | # NuGet Packages
186 | *.nupkg
187 | # NuGet Symbol Packages
188 | *.snupkg
189 | # The packages folder can be ignored because of Package Restore
190 | **/[Pp]ackages/*
191 | # except build/, which is used as an MSBuild target.
192 | !**/[Pp]ackages/build/
193 | # Uncomment if necessary however generally it will be regenerated when needed
194 | #!**/[Pp]ackages/repositories.config
195 | # NuGet v3's project.json files produces more ignorable files
196 | *.nuget.props
197 | *.nuget.targets
198 |
199 | # Microsoft Azure Build Output
200 | csx/
201 | *.build.csdef
202 |
203 | # Microsoft Azure Emulator
204 | ecf/
205 | rcf/
206 |
207 | # Windows Store app package directories and files
208 | AppPackages/
209 | BundleArtifacts/
210 | Package.StoreAssociation.xml
211 | _pkginfo.txt
212 | *.appx
213 | *.appxbundle
214 | *.appxupload
215 |
216 | # Visual Studio cache files
217 | # files ending in .cache can be ignored
218 | *.[Cc]ache
219 | # but keep track of directories ending in .cache
220 | !?*.[Cc]ache/
221 |
222 | # Others
223 | ClientBin/
224 | ~$*
225 | *~
226 | *.dbmdl
227 | *.dbproj.schemaview
228 | *.jfm
229 | *.pfx
230 | *.publishsettings
231 | orleans.codegen.cs
232 |
233 | # Including strong name files can present a security risk
234 | # (https://github.com/github/gitignore/pull/2483#issue-259490424)
235 | #*.snk
236 |
237 | # Since there are multiple workflows, uncomment next line to ignore bower_components
238 | # (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
239 | #bower_components/
240 |
241 | # RIA/Silverlight projects
242 | Generated_Code/
243 |
244 | # Backup & report files from converting an old project file
245 | # to a newer Visual Studio version. Backup files are not needed,
246 | # because we have git ;-)
247 | _UpgradeReport_Files/
248 | Backup*/
249 | UpgradeLog*.XML
250 | UpgradeLog*.htm
251 | ServiceFabricBackup/
252 | *.rptproj.bak
253 |
254 | # SQL Server files
255 | *.mdf
256 | *.ldf
257 | *.ndf
258 |
259 | # Business Intelligence projects
260 | *.rdl.data
261 | *.bim.layout
262 | *.bim_*.settings
263 | *.rptproj.rsuser
264 | *- [Bb]ackup.rdl
265 | *- [Bb]ackup ([0-9]).rdl
266 | *- [Bb]ackup ([0-9][0-9]).rdl
267 |
268 | # Microsoft Fakes
269 | FakesAssemblies/
270 |
271 | # GhostDoc plugin setting file
272 | *.GhostDoc.xml
273 |
274 | # Node.js Tools for Visual Studio
275 | .ntvs_analysis.dat
276 | node_modules/
277 |
278 | # Visual Studio 6 build log
279 | *.plg
280 |
281 | # Visual Studio 6 workspace options file
282 | *.opt
283 |
284 | # Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
285 | *.vbw
286 |
287 | # Visual Studio LightSwitch build output
288 | **/*.HTMLClient/GeneratedArtifacts
289 | **/*.DesktopClient/GeneratedArtifacts
290 | **/*.DesktopClient/ModelManifest.xml
291 | **/*.Server/GeneratedArtifacts
292 | **/*.Server/ModelManifest.xml
293 | _Pvt_Extensions
294 |
295 | # Paket dependency manager
296 | .paket/paket.exe
297 | paket-files/
298 |
299 | # FAKE - F# Make
300 | .fake/
301 |
302 | # CodeRush personal settings
303 | .cr/personal
304 |
305 | # Python Tools for Visual Studio (PTVS)
306 | __pycache__/
307 | *.pyc
308 |
309 | # Cake - Uncomment if you are using it
310 | # tools/**
311 | # !tools/packages.config
312 |
313 | # Tabs Studio
314 | *.tss
315 |
316 | # Telerik's JustMock configuration file
317 | *.jmconfig
318 |
319 | # BizTalk build output
320 | *.btp.cs
321 | *.btm.cs
322 | *.odx.cs
323 | *.xsd.cs
324 |
325 | # OpenCover UI analysis results
326 | OpenCover/
327 |
328 | # Azure Stream Analytics local run output
329 | ASALocalRun/
330 |
331 | # MSBuild Binary and Structured Log
332 | *.binlog
333 |
334 | # NVidia Nsight GPU debugger configuration file
335 | *.nvuser
336 |
337 | # MFractors (Xamarin productivity tool) working folder
338 | .mfractor/
339 |
340 | # Local History for Visual Studio
341 | .localhistory/
342 |
343 | # BeatPulse healthcheck temp database
344 | healthchecksdb
345 |
346 | # Backup folder for Package Reference Convert tool in Visual Studio 2017
347 | MigrationBackup/
348 |
349 | # Ionide (cross platform F# VS Code tools) working folder
350 | .ionide/
351 |
352 | # Ignore our generated code.
353 | references/**/*.json
354 | references/**/*.yaml
355 | references/**/*.ts
--------------------------------------------------------------------------------
/.vscode/launch.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "0.2.0",
3 | "configurations": [
4 | {
5 | // Use IntelliSense to find out which attributes exist for C# debugging
6 | // Use hover for the description of the existing attributes
7 | // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
8 | "name": ".NET Core Launch (web)",
9 | "type": "coreclr",
10 | "request": "launch",
11 | "preLaunchTask": "build",
12 | // If you have changed target frameworks, make sure to update the program path.
13 | "program": "${workspaceFolder}/api/bin/Debug/net6.0/api.dll",
14 | "args": [],
15 | "cwd": "${workspaceFolder}/api",
16 | "stopAtEntry": false,
17 | // Enable launching a web browser when ASP.NET Core starts. For more information: https://aka.ms/VSCode-CS-LaunchJson-WebBrowser
18 | "serverReadyAction": {
19 | "action": "openExternally",
20 | "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
21 | },
22 | "env": {
23 | "ASPNETCORE_ENVIRONMENT": "Development"
24 | },
25 | "sourceFileMap": {
26 | "/Views": "${workspaceFolder}/Views"
27 | }
28 | },
29 | {
30 | "name": ".NET Core Attach",
31 | "type": "coreclr",
32 | "request": "attach"
33 | }
34 | ]
35 | }
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "2.0.0",
3 | "tasks": [
4 | {
5 | "label": "build",
6 | "command": "dotnet",
7 | "type": "process",
8 | "args": [
9 | "build",
10 | "${workspaceFolder}/api/api.csproj",
11 | "/property:GenerateFullPaths=true",
12 | "/consoleloggerparameters:NoSummary"
13 | ],
14 | "problemMatcher": "$msCompile"
15 | },
16 | {
17 | "label": "publish",
18 | "command": "dotnet",
19 | "type": "process",
20 | "args": [
21 | "publish",
22 | "${workspaceFolder}/api/api.csproj",
23 | "/property:GenerateFullPaths=true",
24 | "/consoleloggerparameters:NoSummary"
25 | ],
26 | "problemMatcher": "$msCompile"
27 | },
28 | {
29 | "label": "watch",
30 | "command": "dotnet",
31 | "type": "process",
32 | "args": [
33 | "watch",
34 | "run",
35 | "${workspaceFolder}/api/api.csproj",
36 | "/property:GenerateFullPaths=true",
37 | "/consoleloggerparameters:NoSummary"
38 | ],
39 | "problemMatcher": "$msCompile"
40 | }
41 | ]
42 | }
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Charles Chen
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # .NET 6 OpenAPI with TypeScript Client Generation
2 |
3 | This is a sample application demonstrating .NET 6 with OpenAPI client code generation.
4 |
5 | While gRPC and GraphQL seem to be *en vogue*, REST with OpenAPI offers many of the same benefits in terms of contract and client generation. REST can't match subscriptions and streaming capabilities built into gRPC and GraphQL (not to mention the other features on those platforms), but it's hard to beat the universal support for simple HTTP request/responses, ease of development, linear and predictable scaling of complexity, and maturity of REST.
6 |
7 | OpenAPI makes it more productive than ever to work with REST APIs and paired with managed WebSockets via [Azure SignalR](https://azure.microsoft.com/en-us/services/signalr-service/) or [Azure Web PubSub](https://azure.microsoft.com/en-us/services/web-pubsub/), building low-complexity, high performance web APIs is easier than ever.
8 |
9 | See for more discussion and my thoughts on gRPC, GraphQL, and REST: https://charliedigital.com/2021/11/25/net-6-web-apis-openapi-typescript-client-generation/
10 |
11 | ## Google Cloud Run Version
12 |
13 | If you want to see how to deploy this into Google Cloud Run, check out the branch here: https://github.com/CharlieDigital/dotnet6-openapi/tree/dockerized
14 |
15 | ## Organization
16 |
17 | This project is set up as a mono-repo for simplicity.
18 |
19 | - `root`
20 | - `api` contains the .NET 6 web API
21 | - `web` contains the static web front-end in **Svelte**
22 | - `references` contains the generated client reference
23 | - `web-vue` contains the static web front-end in **Vue**
24 |
25 | ## DIY
26 |
27 | ### .NET Web API
28 |
29 | Start by creating the directory for the API:
30 |
31 | ```
32 | mkdir api
33 | cd api
34 | ```
35 |
36 | Then we set up the .NET 6 Web API project:
37 |
38 | ```
39 | dotnet new webapi
40 | ```
41 |
42 | This will create a default project using the .NET web APIs.
43 |
44 | You can start this project by running
45 |
46 | ```
47 | dotnet run
48 | ```
49 |
50 | You'll see output like the following:
51 |
52 | ```
53 | C:\Users\chenc\Code\OSS\dotnet6-openapi\api>dotnet run
54 | Building...
55 | info: Microsoft.Hosting.Lifetime[14]
56 | Now listening on: https://localhost:7277
57 | info: Microsoft.Hosting.Lifetime[14]
58 | Now listening on: http://localhost:5133
59 | info: Microsoft.Hosting.Lifetime[0]
60 | Application started. Press Ctrl+C to shut down.
61 | info: Microsoft.Hosting.Lifetime[0]
62 | Hosting environment: Development
63 | info: Microsoft.Hosting.Lifetime[0]
64 | Content root path: C:\Users\chenc\Code\OSS\dotnet6-openapi\api\
65 | ```
66 |
67 | Opening your browser to `https://localhost:7277` will display an empty page.
68 |
69 | However, you can view your OpenAPI schema here:
70 |
71 | ```
72 | https://localhost:7277/swagger/v1/swagger.json
73 | ```
74 |
75 | And view the UI here:
76 |
77 | ```
78 | https://localhost:7277/swagger/index.html
79 | ```
80 |
81 | ### Generating Swagger at Build
82 |
83 | This default mechanism works great if you plan on generating your OpenAPI schemas at runtime. But if you want to generate your OpenAPI at build time, we'll need to add some tooling.
84 |
85 | We'll be adding a [Svelte](https://svelte.dev/) UI with [vite](https://vitejs.dev/) later. But we'll need to set up our folder now (since we can't initialize the template into an non-empty directory) and then switch back to `api`
86 |
87 | ```
88 | cd ../
89 | yarn create vite web --template svelte-ts
90 | cd web
91 | yarn
92 | mkdir references
93 | cd references
94 | mkdir codegen
95 | cd ../../api
96 | ```
97 |
98 | We've created a basic Svelte TypeScript application that will be built with vite.
99 |
100 | These next steps are adapted from: https://khalidabuhakmeh.com/generate-aspnet-core-openapi-spec-at-build-time
101 |
102 | First, we'll need to install tooling to generate the schema at build time.
103 |
104 | ```
105 | dotnet new tool-manifest
106 | dotnet tool install SwashBuckle.AspNetCore.Cli
107 | ```
108 |
109 | The `.csproj` file needs to be modified to invoke the CLI
110 |
111 | Update the `csproj` file:
112 |
113 | ```xml
114 |
115 |
116 | net6.0
117 |
118 |
119 |
120 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
128 | ```
129 |
130 | Now when you run
131 |
132 | ```
133 | dotnet build
134 | ```
135 |
136 | This will generate the two files in our `web/references` directory.
137 |
138 | ### Generating TypeScript Client
139 |
140 | This gets us 2/3 of the way there. Now we want to generate a TypeScript client automatically from our schema so that we don't have to perform raw AJAX calls.
141 |
142 | Since our client will be used for a static web front-end, we can use `npm` or `yarn` to generate our client using the `openapi-typescript-codegen` project.
143 |
144 | - https://www.npmjs.com/package/openapi-typescript-codegen
145 | - https://yarnpkg.com/package/openapi-typescript
146 |
147 | We'll use `yarn` for this walkthrough.
148 |
149 | ```
150 | cd ../web
151 | yarn add --dev openapi-typescript-codegen
152 | yarn openapi --input references/swagger.json --output references/codegen --client axios --postfix Service --useOptions --useUnionTypes
153 | ```
154 |
155 | This will use the schemas to generate the *client TypeScript* for interacting with our services 🎉
156 |
157 | ### Automating with Yarn
158 |
159 | To simplify this, we can create a script that builds the full chain from the web project.
160 |
161 | Still in the `web` directory, modify the `package.json` file to add a script:
162 |
163 | ```json
164 | {
165 | // ...
166 | "scripts": {
167 | "codegen": "cd ../api && dotnet build && cd ../web && yarn openapi --input references/swagger.json --output references/codegen --client axios --postfix Service --useOptions --useUnionTypes"
168 | // ...
169 | }
170 | // ...
171 | }
172 | ```
173 |
174 | Now if we run `yarn run codegen` from the `web` project, this will:
175 |
176 | 1. Build our .NET 6 WebAPI project
177 | 2. Generate an updated `swagger.json` and `swagger.yaml` file in the `web/references` directory
178 | 3. Generate an updated TypeScript client in the `web/references/client` directory
179 |
180 | Sweet!
181 |
182 | ### Building the Front-end
183 |
184 | Before we start updating the Svelte app, we'll need to update our API to allow CORS since the apps are at two different URLs.
185 |
186 | In `program.cs`, we add:
187 |
188 | ```csharp
189 | // We need this to call our API from the static front-end
190 | app.UseCors(options => {
191 | options.AllowAnyHeader();
192 | options.AllowAnyMethod();
193 | options.AllowAnyOrigin();
194 | });
195 | ```
196 |
197 | anywhere before `app.Run()`. In a separate terminal in the `api` directory, start our API with `dotnet run`. Pay attention to the port.
198 |
199 | Now let's get back to our front-end.
200 |
201 | To see it, we switch into the `web` directory and run `yarn dev`
202 |
203 | ```
204 | yarn dev
205 | ```
206 |
207 | This will start our application and load it in the default browser.
208 |
209 | the `App.svelte` file is what we're going to modify.
210 |
211 | In the top `
12 |