public class ValuesController : Controller
{
[HttpGet]
[Route("api/teams")]
public IActionResult GetTeams()
{
var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
return Ok(teams);
}
[HttpPost]
[Route("api/team")]
public IActionResult PostTeam([FromBody]Team team)
{
var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
teams.Add(team);
System.IO.File.WriteAllText("jsonFile.json",JsonConvert.SerializeObject(teams));
return Ok(team);
}
// etc...Posts tagged with 'csadvent'
What is the C# Advent?
The C# Advents in 2018 and 2017 were so much fun. It's now time to sign up for 2019.
Just like last year, each day of the Advent calendar will have up to TWO blog posts. That means that there is a maximum of FIFTY slots! So, tell your C# friends and let's fill up this calendar.
A little history: I heard about the F# Advent Calendar, a tradition that's been carried on since 2010 (2014 in English). I think this is a great idea, and so I organized one for C#! (I asked Sergey Tihon for permission!). If you are running other developer advent calendars, just let me know and I will link to them here:
Let's Get Started
I need you to write a C# blog post, create a video, write an article, etc.
Here are the rules:
- Reserve a slot on Twitter (with hash tag #csadvent) or leave a comment on this post. You do not have to announce your topic until the day you reserve.
- Prepare your content (in English).
- Add a link in your content that links back to here, so that your readers may find the entire advent. You can host your content anywhere you'd like: your own site, dev.to, hackernoon, medium, wordpress, youtube, dzone, etc.
- Publish your content on the specified date. Your content must be related to C# in some way, but otherwise the content is completely up to you. I've posted a few ideas below to get your creativity flowing.
- Share your post on Twitter with hashtags #csharp and #csadvent
Below are all the slots, and who has claimed each date.
I will do my best to keep this up to date. The slots will be first come first serve. I also allowed last year's authors to get first crack. I will claim the last remaining spot for myself. I will prepare a post just in case someone has to drop out.
Alternates:
- IF ALL FIFTY SLOTS FILL UP, please leave a comment or tweet with #csadvent anyway and I'll put you on this standby list:
- Standby list:
- Myself.
- You, if you want to be.
Some ideas/topics to help inspire you:
- Blazor - C# for the browser
- Your latest open source contribution - show the community how you contributed and why
- Your favorite C# language feature - it doesn't even have to be a new feature, just blog about something you love about C#
- Introduce your favorite NuGet package / library. Even if it's a library you take for granted, not everyone has heard about it.
- How to avoid a pitfall you found with performance/memory/etc
- Integration/deployment of a C# application with Jenkins, Docker, Kubernetes, TeamCity, Azure, etc
- Write a "how to" for one of the many tools discussed in an episode of the Cross Cutting Concerns podcast or the DotNetBytes podcast
- Interview someone about C# and post the audio or a transcript.
- Implement a simplified example of a design pattern in C#
Thanks to everyone who is participating!
If you were an author of a C# Advent blog post in 2018, you get a chance to sign up earlier than the general public.
Tweet #csadvent or leave a comment below with the date you want to blog on. Each day has up to TWO slots. If someone has already claimed the day you want, that day may still be available.
The general call for C# Advent authors will go out soon, so please claim your dates as soon as possible. Just like last year, you do NOT have to pick a topic right now. If you DO want to pick a topic, I will pencil it in, but you are free to change it at any time up until the date you pick.
Last year's C# Advent was a success beyond anything I expected. I was worried that I wouldn't get enough sign-ups, but I ended up turning some people away. I was worried that people wouldn't get their blog posts done on time, but every single author delivered on time. I was worried there would be too much overlap in topics. There was a tiny bit, but every author's post had a unique, quality perspective, even if there was some overlap.
So, I'm doubling down this year! Each day of the Advent calendar will have up to TWO blog posts. That means that there is a maximum of FIFTY slots! So, tell your C# friends and let's fill up this calendar.
A little history: I heard about the F# Advent Calendar, a tradition that's been carried on since 2010 (2014 in English) and is still going strong in 2018. I think this is a great idea, and so I organized one for C#! (I asked Sergey Tihon for permission!). Other Advent calendars: C# Advent Calendar (in Spanish), Q# Advent Calendar.
So, I need you to write a C# blog post!
Here are the rules:
- Reserve a slot on Twitter (with hash tag #csadvent) or leave a comment on this post. You do not have to announce your topic until the day you reserve.
- Prepare a blog post (in English).
- Add a link in your blog post that links back to here, so that your readers may find the entire advent.
- Publish your blog post on the specified date. Your post must be related to C# in some way, but otherwise the content is completely up to you. I've posted a few ideas below to get your creativity flowing.
- Share your post on Twitter with hashtags #csharp and #csadvent
Below are all the slots, and who has claimed each date.
I will do my best to keep this up to date. The slots will be first come first serve. I also allowed last year's authors to get first crack. I have already claimed one of the December 25th slots for myself, but I can be persuaded to change if you really want that date.
Alternates:
- IF ALL FIFTY SLOTS FILL UP, please leave a comment or tweet with #csadvent anyway!
- I will put you on this 'standby' list in case someone drops out or can't deliver their post in time.
- Standby list:
- Corstiaan Hesselink
Some ideas/topics to help inspire you:
- Blazor - now's your chance to experiment with writing C# for the browser
- Your latest open source contribution - show the community how you contributed and why
- Your favorite C# language feature - it doesn't even have to be a new feature, just blog about something you love about C#
- Introduce your favorite NuGet package / library. Even if it's a library you take for granted, not everyone has heard about it.
- How to avoid a pitfall you found with performance/memory/etc
- Integration/deployment of a C# application with Jenkins, Docker, Kubernetes, TeamCity, Azure, etc
- Write a "how to" for one of the many tools discussed in an episode of the Cross Cutting Concerns podcast
- Create a video tutorial and embed it in your blog post.
- Interview someone about C# and embed an audio player in your blog post.
- Implement a simplified example of a design pattern in C#
Thanks to everyone who is participating!
If you were an author of a C# Advent blog post in 2017, you get a chance to sign up earlier than the general public.
Tweet #csadvent or leave a comment below with the date you want to blog on. Note that this year, each day has up to TWO slots. So if someone has already claimed the day you want, that day may still be available.
The general call for C# Advent authors will go out next week, so claim your dates as soon as possible. Just like last year, you do NOT have to pick a topic right now. If you DO want to pick a topic, I will pencil it in, but you are free to change it at any time up until the date you pick.
Swashbuckle is a handy library to easily bring Swagger support to your ASP.NET Core (or ASP.NET) application. It is especially handy when developing an HTTP based API. It creates a form of interactive documentation based on the OpenAPI Specification.
Before diving into Swashbuckle: Merry Christmas! This blog is being posted on December 25th, 2017. It’s the final post of the very first C# Advent Calendar. Please check out the other 24 posts in the series! This event has gone so well, that I’m already planning on doing it again in 2018. Thank you, again, to everyone who participated (whether you are a writer or you’ve just been following along).
The full source code used in this example is available on Github.
ASP.NET Core HTTP API
I’m going to assume some level of familiarity with ASP.NET Core and creating a REST API. Here’s an example of a GET and a POST. These endpoints are reading/writing from a JSON text file (in a way that is probably not thread-safe and definitely not efficient, but it’s fine for this example).
To try out the GET endpoint, the simplest thing I can do is open a browser and view the results. But to try out the POST endpoint, I need something else. I could install Postman or Fiddler (and you should). Here’s how that would look.
Postman is great for interacting with endpoints, but Postman alone doesn’t really tell us anything about the endpoint or the system as a whole. This is where Swagger comes in.
Swagger
Swagger is a standard way to provide specifications for endpoints. Usually, that specification is automatically generated and then used to generate an interactive UI.
We could write the Swagger spec out by hand, but fortunately ASP.NET Core provides enough information to generate a spec for us. Look at the PostTeam action above. Just from reading that we know:
-
It expects a POST
-
The URL for it is
/api/team -
There’s a
Teamclass that we can look at to see what kind of body is expected
From that, we could construct a Swagger spec like the following (I used JSON, you can also use YAML).
{
"swagger": "2.0",
"info": { "version": "v1", "title": "Sports API" },
"basePath": "/",
"paths": {
"/api/team": {
"post": {
"consumes": ["application/json"],
"parameters": [{
"name": "team",
"in": "body",
"required": false,
"schema": { "$ref": "#/definitions/Team" }
}]
}
}
},
"definitions": {
"Team": {
"type": "object",
"properties": {
"name": { "type": "string" },
"stadiumName": { "type": "string" },
"sport": { "type": "string" }
}
}
}
}But why on earth would you want to type that out? Let’s bring in a .NET library to do the job. Install Swashbuckle.AspNetCore with NuGet (there’s a different package if you want to do this with ASP.NET).
You’ll need to add a few things to Startup.cs:
In the ConfigureServices method:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1"});
});In the Configure method:
app.UseSwagger();Aside: With ASP.NET, NuGet actually does all this setup work for you.
Once you’ve done this, you can open a URL like http://localhost:9119/swagger/v1/swagger.json and see the generated JSON spec.
Swagger UI with Swashbuckle
That spec is nice, but it would be even nicer if we could use the spec to generate a UI.
Back in the Configure method, add this:
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sports API v1");
});Now, open your site and go to /swagger:
Some cool things to notice:
-
Expand/collapse by clicking the URL of an endpoint (note that you must use
Routeattributes for Swashbuckle to work with ASP.NET Core). -
"Try it out!" buttons. You can execute GET/POST right from the browser
-
The "parameter" of the POST method. Not only can you paste in some content, but you get an example value that acts like a template (just click it).
Giving some swagger to your Swagger
Swagger and Swashbuckle have done a lot with just a little bit. It can do even more if we add a little more information in the code.
-
Response: The
ProducesResponseTypeattribute will let Swagger know what the response will look like (this is especially useful if you are usingIActionResultand/or an endpoint could return different types in different situations). -
Comments: If you are using XML comments, you can have these included with the Swagger output.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1" });
var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
c.IncludeXmlComments(filePath);
});(Also make sure you XML Documentation output for your project enabled)
Here’s an example of a GetTeams method with both XML comments and ProducesResponseType:
/// <summary>
/// Gets all the teams stored in the file
/// </summary>
/// <remarks>Baseball is the best sport</remarks>
/// <response code="200">List returned succesfully</response>
/// <response code="500">Something went wrong</response>
[HttpGet]
[Route("api/teams2")]
[ProducesResponseType(typeof(Team), 200)]
public IActionResult GetTeams2()
{
var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
return Ok(teams);
}-
Customize your info: there’s more to the
Infoclass than just Title and Version. You can specify a license, contact, etc.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Title = "Sports API",
Version = "v1",
Description = "An API to list and add sports teams",
TermsOfService = "This is just an example, not for production!",
Contact = new Contact
{
Name = "Matthew Groves",
Url = "https://crosscuttingconcerns.com"
},
License = new License
{
Name = "Apache 2.0",
Url = "http://www.apache.org/licenses/LICENSE-2.0.html"
}
});
var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
c.IncludeXmlComments(filePath);
});Here’s a screenshot of the UI that has all three of the above enhancements: response type, XML comments, and more customized info.
Summary
Working on HTTP-based APIs? Bring Swashbuckle and Swagger into your life!
More resources:
-
I recorded a couple of videos on getting started with Couchbase that feature Swashbuckle. Check out ASP.NET with Couchbase: Getting Started and ASP.NET Core with Couchbase: Getting Started
-
Swashbuckle for ASP.NET (Github)
-
Swashbuckle for ASP.NET Core (Github)
Thanks again for reading the 2017 C# Advent!
