I prefer using NSwag (it can serve UI with Swagger or ReDoc). The reason is that it can generate typescript or C# client code for you on build. So you never need to implement client code manually for your front end app and it always stays in sync with your API.
The code generation feature is really similar with what is present in postman, in fact they seem to have made a "merge" between swagger and postman features
wdym lack of support for OAuth2? a quick search on scalar documentation shows support for it. app.MapScalarApiReference(options => { options .WithPreferredScheme("OAuth2") // Security scheme name from the OpenAPI document .WithOAuth2Authentication(oauth => { oauth.ClientId = "your-client-id"; oauth.Scopes = ["profile"]; }); });
Looks nice and I would also be interested in seeing an in-depth video about Scalar, regard authenitcation, authorization, with docker (loopback ip - switching from docker and webapp) and YARP etc
3:11 You should specify a relative path for the swagger endpoint, i.e. a path without leading slash. An absolute path (with a leading slash) may break your swagger if the app is located behind a reverse proxy like nginx
The built-in OpenAPI middleware does not show the exact broken endpoints, but Swagger does. In our case, the OpenAPI generation was broken. The built-in middleware only reported "Unsupported HTTP method" without specifying which endpoint caused the issue. However, Swagger clearly identified the problem: duplicated models (shows endpoints and specific models). After fixing this, both solutions worked fine. Due to the lack of helpful debugging information in the built-in middleware, I decided to stick with Swagger.
When running MapOpenApi in a container, the default server is localhost and the port is the internal port. You have to change the uri to / in the OpenApi config so that it works using the relative url
I've implemented Scalar after watching this video and I gotta say: it's great! Especially for 3rd party vendors who will be using our API. The built-in code samples for various languages will make it very easy for our partners to integrate our API. I just need to figure out the Authentication side of Scalar.
Thanks for introducing the new brand Ui which is Scaler. it is better than the Swagger but has one problem which is seeing endpoint and models and properties of models are aside from each other
@@SkrekkLich You don't have to use the string extensions if you don't like. There are other ways to init a request and clean up the api for your liking.
I like this move to optionally add back in the UI portion. Although, it would have been nice to be a template option/switch to include it automagically
I'd love to see a full demo of scalar. I have several projects that use swagger and have authentication built in for testing so seeing how to set that up would probably get me to make the switchover before i even move to .Net 9
Does the built-in openapi feature infer methods in controllers without the HttpMethod attribute and complex objects in parameters without the [FromBody]?
I used OpenAPI before I discovered swagger years ago. The only reason I liked it was to test submission of data. Scalar looks really good, the natural successor particularly with the dummy code
I liked the idea of showing PUT, POST, … with different colors. Hopefully it can be done with this library. These UIs seem to be ‘designed’ by programmers and not UX experts.
We decorate in swagger single.sigon, locks for restricted api's, show api version and link to the api wiki and accept enums as strings. Can you do all this in the new stuff?
The GET which requires no input is fine but how does the test request work when you have specific required inputs like needing a valid user id or valid auth token?
Interesting, but how to combine many modules on one page? If I use 5 or 6 modules with this documentation and want to present it to clients on one page
Can I just point my Postman (or other client) to the openapi endpoint and automatically populate a workspace for my API, or is that not a feature? If it was, UIs like this wouldn't really be necessary.
yes you can, but it's usually not recommended to just remove the environment block as shown in Nick's demo, or .. specifically target for Production if that's what you want.
Will it fix generation openapi doc with nested classes which wasn’t completely perfect according to specifications. I mean generating namespaces with [] ‘ etc .
Interesting. Whats happening with client code generation? I currently use Connected services to auto gen c# wrappers, under the hood it uses nswag. Is that being replaced with similar functionality? Also, how about enum types? swagger can generate named enums rather than integer ranges.
The json that is generated in dotnet 9 will be openapi 3.0 format like today the one generated by swagger, NSWAG only use the json to generate code, so it should work the same even without needing the UI
I see one Huge problem!!! The contract first approach doesn't work here. To develop a web API we need to create a schema first, then we can use this schema to generate the server side controllers, that check incoming requests and outgoing responses against the schema, then we need to inject our business logic into the controllers and finally the implementation compatibility must be checked in the dev and compile time with a static types. Shown in the video approach is not for serious project - you can break your api and get aware of that iafter release n production when your client fails on handling the response.
Detailed video would be great. What about api documentation, like the attributes which give more info about specific endpoint like all possible http response codes and respective models?
Hi Nick, I don't know if you will answer me but, may i know what is the meaning of the repository folder in your minimal api in github? Sorry i was just new to c#. Thank you so much
Doesn't scalar lacks a lot of features though? I don't like Swagger either and I usually just use the json generated in a postman collection anyway. Swagger is old but absolutely reliable and extremely configurable. Changing from gold to copper doesn't look like a good choice to me. It has potential but yeah... still not there.
They have introduced Endpoint explorer to test the apis and also it’s kinda same as rest client extension that was available in vs code but with limited features.
The scalar produced part says "DemoAPI | v1". While `DemoApi` is taken from the AssemblyName of the project, I have not found where the `v1` is coming from and where to change it. Any ideas?
Though I must say, kiota APIs are not the best regarding ergonomics... Refit usually feels more "native" than kiota API call builder-dictionary-parameter-bags
We just ported everything to NET8 and it will remain like that at least 10 years. Everyone in company is sick to "reinvent" everything on monthly basis 😉
I tried to use scalar a few months ago. but the lack PKCE auth workflow made it unusable for my case :( I wish I could use it because I like it way more than swagger
SwaggerUI or Scalar, the test ui is not so relevant. Sure, the featutes can be improved which are nice for testing; but the important stuff in openAPI is the service descriptor json. The openAPI json can be used to generate a client proxy! You can have a fully functional, typesafe client proxy with three clicks or a single cmdline. This proxy class has typed methods for all api endpoints; hiding the implementation details... Essentially the clientside code is 98% the same for corewcf / grpc / rest api serversides; as they all support very similar clientside proxy autogeneration...
How many public facing APIs are there that have clients or would-be clients that don't know how to consume APIs already? Are they really going to learn to code against your API by reading the client-code examples exposed here?
Very cool! But why does everyone like dark mode so much? I cant stand it. When I use dark mode after a while and look away from my monitor, or navigate to a website with a lighter theme, my eyes get all screwy and take a while to adjust. It's almost headache inducing. I've never understood why people like it.
I really like swagger. As someone who does a lot of integration apps, I see a huge difference between having swagger doc to work with and having ... something else
Thank you SIR! I'm starting out as a .NET developer.I'm currently learning from my home PC.Which one would you recommend if I'm looking to get a Laptop or MacBook for work or study? My friends who are already working as developers advised me to buy a MacBook 16/512 or buy a powerful laptop for the same money. What would you recommend? Will there be problems with the MacBook related to the .NET stack?
@fusedqyou Swagger is not a best option for public share and swagger is disabled in production. I am using HTTP request files only for development purposes without sharing API to the outside world. Http request files are fantastic to share across the team. With swagger you close the webpage and your typed requests are gone. They work in VS, VS Code and in Rider@@fusedqyou
Hi Nick, Swagger currently has around 594 million downloads, while Scalar has approximately 16.5K. The purpose of using both Swagger and Scalar is essentially the same, both are tools for API design and documentation. However, it is important to note that neither of them is recommended for use in production environments, as you previously mentioned. Given this, I don’t see any significant differences between these two tools in terms of practical use, I still don't get it why Scalar would be better than Swagger. Maybe you would elaborate! Thanks
@@VindicatorMorty neither. In production you shouldn't need an API explorer. If you must execute requests manually copy paste a curl for example from one of you test stages
@@EikeSchwass okay i get it, should not be directly executable. Thats why read only is mentioned. But using swagger/scalar as documentation is still okay and useful? Was wondering about that point.
That's great, now I can say that the api is scalable :P
Yes and your managers will actually give you a raise because its a word they've heared and think it is awesome and all...
Always was
I prefer using NSwag (it can serve UI with Swagger or ReDoc). The reason is that it can generate typescript or C# client code for you on build. So you never need to implement client code manually for your front end app and it always stays in sync with your API.
Lifechanger
The problem is no one how to use it. So swagger is bad now. 😂
@@Eaglessoft Lol, what's the problem to google it?)
@@tyomios not about google man. Auto gen typescript/javascript code from swagger
When I upgrade to my project to .Net 9 I'm definitely going to checking out scalar... looks great! Thanks for the video 😃
The code generation feature is really similar with what is present in postman, in fact they seem to have made a "merge" between swagger and postman features
Scalar is cool BUT it lacks some important features such as support for OAuth2 and authorization code flow for authentication
Basically impossible to replace swagger
wdym lack of support for OAuth2?
a quick search on scalar documentation shows support for it.
app.MapScalarApiReference(options =>
{
options
.WithPreferredScheme("OAuth2") // Security scheme name from the OpenAPI document
.WithOAuth2Authentication(oauth =>
{
oauth.ClientId = "your-client-id";
oauth.Scopes = ["profile"];
});
});
Thank you for pointing that out!
Looks nice and I would also be interested in seeing an in-depth video about Scalar, regard authenitcation, authorization, with docker (loopback ip - switching from docker and webapp) and YARP etc
3:11 You should specify a relative path for the swagger endpoint, i.e. a path without leading slash.
An absolute path (with a leading slash) may break your swagger if the app is located behind a reverse proxy like nginx
This actually doesn't work. if you don't star with a leading slash it'll assume swagger/yourpath
Scalar looks awesome! Will defdefinitely try this out
The built-in OpenAPI middleware does not show the exact broken endpoints, but Swagger does.
In our case, the OpenAPI generation was broken. The built-in middleware only reported "Unsupported HTTP method" without specifying which endpoint caused the issue. However, Swagger clearly identified the problem: duplicated models (shows endpoints and specific models). After fixing this, both solutions worked fine.
Due to the lack of helpful debugging information in the built-in middleware, I decided to stick with Swagger.
When running MapOpenApi in a container, the default server is localhost and the port is the internal port. You have to change the uri to / in the OpenApi config so that it works using the relative url
I'd love to see a more in-depth on customization possibilities. You don't know what you don't know
I've implemented Scalar after watching this video and I gotta say: it's great! Especially for 3rd party vendors who will be using our API. The built-in code samples for various languages will make it very easy for our partners to integrate our API. I just need to figure out the Authentication side of Scalar.
Did you figure it out? We use JWT Bearer tokens and I have no idea how to set it up.
Thanks for this interesting video, I like how scalar looks like postman
Thanks for introducing the new brand Ui which is Scaler. it is better than the Swagger but has one problem which is seeing endpoint and models and properties of models are aside from each other
hey @arminhabibi149! do you mean how we have the models section in the sidebar below the list of tags/endpoints?
I like the functionality of Scalar you showcased, but I like more the appearance of Swagger.
hey @Sergio_Loureiro we actually have a "classic" layout, which is single column and has all the functionality of Scalar :)
Flurl support would be nice. It's my favorite C# http client implementation by far
Didn't know that, it looks really nice - will use it in my future projects, thanks! :))
huh, neat use of string extensions, awkward to look at at first lol. Will check it out too, thanks :D
@@SkrekkLich You don't have to use the string extensions if you don't like. There are other ways to init a request and clean up the api for your liking.
@@gileee Yeah I saw that they also provide Url and Uri extensions but I find it kinda neat tbh. Was just weird at first seeing it this way.
Absolutely would love to see a tutorial on Scaler
I like this move to optionally add back in the UI portion. Although, it would have been nice to be a template option/switch to include it automagically
I'd love to see a full demo of scalar. I have several projects that use swagger and have authentication built in for testing so seeing how to set that up would probably get me to make the switchover before i even move to .Net 9
Does the built-in openapi feature infer methods in controllers without the HttpMethod attribute and complex objects in parameters without the [FromBody]?
I used OpenAPI before I discovered swagger years ago. The only reason I liked it was to test submission of data. Scalar looks really good, the natural successor particularly with the dummy code
Really cool. Thanks for sharing
Btw. you forgot to mention it has dark mode /s 😁
Does it have dark mode?
@@m4inline It has dark mode
Scalar UI is very promising + the code test also there
Call me old-fashioned, but I still prefer Swagger :P
Old-fashioned!
Me too
I liked the idea of showing PUT, POST, … with different colors. Hopefully it can be done with this library. These UIs seem to be ‘designed’ by programmers and not UX experts.
We decorate in swagger single.sigon, locks for restricted api's, show api version and link to the api wiki and accept enums as strings. Can you do all this in the new stuff?
This. Really want to know if dotnet 9/Scalar supports integrated authentication with OAUTH2 and enum strings, kinda crucial for our workflow.
@@blackpaw29 @health_doc it sure does!
you always have interesting videos. thanks!
Oh damn, Scaler is sick!
Can you make a vid about Kiota? I have a shared project but i cant figure out how to prevent it from regenerating the files and making copies
I started disliking swagger when i integrated with other apis and they had this beautiful and powerful documentation and i had... well... swagger
Swagger supports rich documentation.
Good video Nick 👍
hi nick. Is there a pkce authentication flow support like swagger in scalar.
The GET which requires no input is fine but how does the test request work when you have specific required inputs like needing a valid user id or valid auth token?
Interesting, but how to combine many modules on one page? If I use 5 or 6 modules with this documentation and want to present it to clients on one page
Where is the code it's not in the description?
Can I just point my Postman (or other client) to the openapi endpoint and automatically populate a workspace for my API, or is that not a feature? If it was, UIs like this wouldn't really be necessary.
Great Nick! Thank you!!
How about the api versioning?
Hi Nick. Can I use it for Production? Or is it only for dev environment
yes you can, but it's usually not recommended to
just remove the environment block as shown in Nick's demo, or .. specifically target for Production if that's what you want.
@hj.0301 hi tks. Why is it not for producción ?
@@davidpccode coz you'll be exposing all your APIs
Will it fix generation openapi doc with nested classes which wasn’t completely perfect according to specifications. I mean generating namespaces with [] ‘ etc .
I have implemented some custom Filters for Swagger. Do they need to be migrated, or will they plug and play?
Interesting.
Whats happening with client code generation? I currently use Connected services to auto gen c# wrappers, under the hood it uses nswag. Is that being replaced with similar functionality?
Also, how about enum types? swagger can generate named enums rather than integer ranges.
The json that is generated in dotnet 9 will be openapi 3.0 format like today the one generated by swagger, NSWAG only use the json to generate code, so it should work the same even without needing the UI
@@SulexaPerso Thanks, thats good to know. Be interesting to see if MS plan on implementing their own version of nswag.
I see one Huge problem!!!
The contract first approach doesn't work here.
To develop a web API we need to create a schema first, then we can use this schema to generate the server side controllers, that check incoming requests and outgoing responses against the schema, then we need to inject our business logic into the controllers and finally the implementation compatibility must be checked in the dev and compile time with a static types.
Shown in the video approach is not for serious project - you can break your api and get aware of that iafter release n production when your client fails on handling the response.
thats Great But How About Swagger Authentication ? scalar have it?
Detailed video would be great. What about api documentation, like the attributes which give more info about specific endpoint like all possible http response codes and respective models?
Does Scalar includes data annotations from models? In swagger I could make example requests, etc.
yes we do support that!
Thanks for all your great content Nick!
Would definitely love an in-depth video on open-api and scaler, or maybe even a short free dometrain course
Hi Nick,
I don't know if you will answer me but, may i know what is the meaning of the repository folder in your minimal api in github? Sorry i was just new to c#.
Thank you so much
Doesn't scalar lacks a lot of features though? I don't like Swagger either and I usually just use the json generated in a postman collection anyway. Swagger is old but absolutely reliable and extremely configurable. Changing from gold to copper doesn't look like a good choice to me. It has potential but yeah... still not there.
Looks cool !
We can use Scalar on previous .NET versions right?
yes :)
Great video ... again
Does this work well with an Ocelot API Gateway?
Awesome, thanks
They have introduced Endpoint explorer to test the apis and also it’s kinda same as rest client extension that was available in vs code but with limited features.
Hi Nick, It will be really appriciated if you create detailed video on the new Scalar UI instead of Swagger
I can't see Authorization drop-down in scalar ui
Does it support bearer token authorization like swagger does?
Yes
can we pull this into .net 8 projects?
Sure you can!
The scalar produced part says "DemoAPI | v1".
While `DemoApi` is taken from the AssemblyName of the project, I have not found where the `v1` is coming from and where to change it.
Any ideas?
From DocumentName, as default it's "v1"
@@jorgequirino8536 could you explain more? where is this DocumentName and v1 ?
Someone knows any tool or how use the swagger to add event information?
I don't like it. Swagger has UI part that allows you to switch versions from UI, with that lib you have to type it in URL...
We can choose any UI to implement now, there wasn’t anything special about the built in Swagger stuff
@@JollyGiant19 I meant that I like that MS added openAPI. But I don't like scalar and still prefer SwaggerUI
Client codegen wise Kiota is also an option.
Though I must say, kiota APIs are not the best regarding ergonomics... Refit usually feels more "native" than kiota API call builder-dictionary-parameter-bags
@@Kirides that's probably because refit only generates c# client
We just ported everything to NET8 and it will remain like that at least 10 years. Everyone in company is sick to "reinvent" everything on monthly basis 😉
You haven’t seen reinvention until you’ve seen the JavaScript ecosystem. This is a especially minor change
I tried to use scalar a few months ago. but the lack PKCE auth workflow made it unusable for my case :( I wish I could use it because I like it way more than swagger
hi @lemoncrazedcamel! we did a revamp on our auth, and are looking into adding PKCE auth workflow next :)
SwaggerUI or Scalar, the test ui is not so relevant. Sure, the featutes can be improved which are nice for testing; but the important stuff in openAPI is the service descriptor json.
The openAPI json can be used to generate a client proxy! You can have a fully functional, typesafe client proxy with three clicks or a single cmdline. This proxy class has typed methods for all api endpoints; hiding the implementation details...
Essentially the clientside code is 98% the same for corewcf / grpc / rest api serversides; as they all support very similar clientside proxy autogeneration...
Scalar is the future, Swagger is now.
Don't know about Scaler but its looks so amazing. Thank you Nick
is it free? does not look like it but no pricing found either
It’s free
How many public facing APIs are there that have clients or would-be clients that don't know how to consume APIs already? Are they really going to learn to code against your API by reading the client-code examples exposed here?
Uncredible video, thank you, Nick! I always wondered why swagger defaults are just not good enough for 2024
lol, what has 2024 to do with that. smh.
@@mostrealtutu it just feels outdated, idk. I mean the design
@@stassss2011 hehe ok, ill allow that :)
@@stassss2011 what about MS SQL Server Management Studio's or MS Visual Studio's designs?
Aren't they outdated as well?
IMHO they are!
Thought I was the only one that didn't like Swagger. This looks fun to try out. You've done it again, thanks Nick.
Very good! ❤
Now it doesn't work for him to "insert" an example of a request into the "body" 😢
ReDoc is ok too as ui
Very cool! But why does everyone like dark mode so much? I cant stand it. When I use dark mode after a while and look away from my monitor, or navigate to a website with a lighter theme, my eyes get all screwy and take a while to adjust. It's almost headache inducing. I've never understood why people like it.
I prefer Scalar.
Spotlight
That's great
Are you using visual studio 2022? For mac, what should i use?
Shiny object syndrom
I really like swagger. As someone who does a lot of integration apps, I see a huge difference between having swagger doc to work with and having ... something else
OpenAPI...MinimalAPI...
Leave me with my OLD looking C# )
Thank you SIR! I'm starting out as a .NET developer.I'm currently learning from my home PC.Which one would you recommend if I'm looking to get a Laptop or MacBook for work or study?
My friends who are already working as developers advised me to buy a MacBook 16/512 or buy a powerful laptop for the same money. What would you recommend? Will there be problems with the MacBook related to the .NET stack?
I like my swagger!
Is Scalar also available pre .net 9?
Yes, for .NET 8 as well!
I will personally use HTTP Request Files in Rider and Postman
This is not the same. The .http files are manually crafted for development and should not be publicly shared. They also do not work outside of VS.
How would you share that with QA and product managers ?
@fusedqyou Swagger is not a best option for public share and swagger is disabled in production.
I am using HTTP request files only for development purposes without sharing API to the outside world.
Http request files are fantastic to share across the team. With swagger you close the webpage and your typed requests are gone.
They work in VS, VS Code and in Rider@@fusedqyou
@@KazLA QA? Is that still a thing? I thought QA is obsolete...
@@johnnyblue4799 Only at the myopic companies
Is he really using intellij for dotnet
It's called Rider
Thanks! Good video, nice thing. Is it possible to implement this solution already in .NET8? If yes, is there something to note?
You can totally use it in .NET 8
Scalar looks neat!! Swagger UI is really outdated, the lack of a side menu baffles me.
However... Isn't Scala a paid product?
3.0.1 not 3.1.0 ????? Really?????
Microsoft.OpenAPI just does not support it yet
Try use basepath. Don't working correctly
Does anyone sue Microsoft for stealing other people's ideas?
Typical but they need build a first citizen ui
Hi Nick,
Swagger currently has around 594 million downloads, while Scalar has approximately 16.5K.
The purpose of using both Swagger and Scalar is essentially the same, both are tools for API design and documentation. However, it is important to note that neither of them is recommended for use in production environments, as you previously mentioned.
Given this, I don’t see any significant differences between these two tools in terms of practical use, I still don't get it why Scalar would be better than Swagger.
Maybe you would elaborate!
Thanks
Hi Vahid,
.NET Framework has 4B downloads, .NET Core has 100M.
Nick
So @nickchapsas, you mean to wait for some time while Scalar will be mature enough and then use it?😀
Could you elaborate on what someone should use in a production environment?
@@VindicatorMorty neither. In production you shouldn't need an API explorer. If you must execute requests manually copy paste a curl for example from one of you test stages
@@EikeSchwass okay i get it, should not be directly executable. Thats why read only is mentioned. But using swagger/scalar as documentation is still okay and useful? Was wondering about that point.
Ummm... it's nice but I don't see a lot of value yet
M$ might provide an option for users to switch the debug UI instead of removing such a familiar tool that has been used for many years.
We can use any of them we want, you don’t have to use the default one Swagger gave us.
BYE SWAGGER
No
I have never seen the need for Swagger. If you write your code correct it is not needed.
"Microsoft App", "OpenApi", who at microsoft is naming these??? for the love of all that is C# , STOP