{"id":15091233,"url":"https://github.com/surender1987/webapidocumentationwithswagger","last_synced_at":"2026-02-12T10:04:23.482Z","repository":{"id":177927638,"uuid":"231731439","full_name":"Surender1987/WebAPIDocumentationWithSwagger","owner":"Surender1987","description":"ASP.Net core web api with swagger","archived":false,"fork":false,"pushed_at":"2020-01-04T11:19:59.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T10:48:15.636Z","etag":null,"topics":["dotnet","dotnet-core","dotnetcore","dotnetcore3","openapi","swagger","swagger-api","swagger-docs","swagger-specification","swagger-ui","swagger2","web-api"],"latest_commit_sha":null,"homepage":null,"language":"C#","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/Surender1987.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":"2020-01-04T08:21:50.000Z","updated_at":"2020-01-04T11:27:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"180b86fd-ad63-42b6-98f3-adeb7ee55cbd","html_url":"https://github.com/Surender1987/WebAPIDocumentationWithSwagger","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"a9eba5f7dec43e82d216221573b08aa3dbe4d9d6"},"previous_names":["surender1987/webapidocumentationwithswagger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Surender1987/WebAPIDocumentationWithSwagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surender1987%2FWebAPIDocumentationWithSwagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surender1987%2FWebAPIDocumentationWithSwagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surender1987%2FWebAPIDocumentationWithSwagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surender1987%2FWebAPIDocumentationWithSwagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Surender1987","download_url":"https://codeload.github.com/Surender1987/WebAPIDocumentationWithSwagger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Surender1987%2FWebAPIDocumentationWithSwagger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270982194,"owners_count":24679447,"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","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["dotnet","dotnet-core","dotnetcore","dotnetcore3","openapi","swagger","swagger-api","swagger-docs","swagger-specification","swagger-ui","swagger2","web-api"],"created_at":"2024-09-25T10:36:35.904Z","updated_at":"2026-02-12T10:04:23.416Z","avatar_url":"https://github.com/Surender1987.png","language":"C#","readme":"# ASP.net core web api documentation with swagger/openApi\nIn the world of web api and microservices, understanding web api's methods and endpoints is quite challenging. Traditional way to create documentation as file with word or PDF. But it is very difficult to maintained and keeping documentation updated as per changes. Now swagger which also known as openAPI solves the problem of web api documentation and testing.\n\n## What is Swagger/OpenAPI?\nSwagger is a language-agnostic specification for describing REST APIs. Swagger project was donated to OpenAPI Initiative where it is called as openAPI. So both these names are used interchangeably. Swagger/OpenAPI allows both human and computers to understand capabilities of web api without interacting its implementation (code, deployments etc). There are two main goals are\n\n1. Minimize the time and effort to connect two disconnected services. \n2. Minimize time and effort for web api documentation\n\nIn this document we will went through \u003cb\u003eSwashbuckle.Aspnetcore\u003c/b\u003e and \u003cb\u003eNSwag.net\u003c/b\u003e\n\n\u003cb\u003eSwashbuckle.Aspnetcore\u003c/b\u003e - Swashbuckle.aspnetcore is an open source project for .net core documentation.\n\n\u003cb\u003eNSwag.net\u003c/b\u003e - NSwag.net is another open source project for .net core web api documentation, additionally provide capabilities of creating C# and TypeScript clients for web api.\n\n## Starting with swashbuckle and aspnet core\nSwashbuckle.AspNetCore mainly consists of three components\n\n\u003cb\u003eSwashbuckle.AspNetCore.Swagger\u003c/b\u003e - Swagger object and middleware to expose SwaggerDocument object as JSON.\n\n\u003cb\u003eSwashbuckle.AspNetCore.SwaggerGen\u003c/b\u003e - Swagger generator which builds SwaggerDocument directly from web api controllers and models. It typically combines swagger endpoint middleware to automatically expose swagger JSON.\n\n\u003cb\u003eSwashbuckle.AspNetCore.SwaggerUI\u003c/b\u003e - It interpret swagger json and create UI for web api.\n\nFor implementation, i am using visual studio 2019 with .Net core 3.1. Here are steps \n\n1. Open visual studio 2019 and create a new project with template ASP.Net core web application and select web api type project\n2. Install nuget pckage \"Swashbuckle.AspNetCore\" for now its pre-release so i am using version 5.0.0-rc5.\n   Open Solution Explorer --\u003e Right click to dependencies folder --\u003e select manage nuget package option --\u003e Search for Swashbuckle.AspNetCore --\u003e Install\n3. Next step is to modify our startup class to add swagger dependencies and middlewares\n\nImport following namespace\n\nusing Microsoft.OpenApi.Models;\n\nAdd swagger generator to the services collection by adding below code to Startup.ConfigureServices method\n\nservices.AddSwaggerGen(conf =\u003e\u003cbr /\u003e\n{\u003cbr /\u003e\n  conf.SwaggerDoc(\"v1\", new OpenApiInfo {\u003cbr /\u003e\n      Title=\"Api documentation\",\u003cbr /\u003e\n      Version = \"1.0.0\"\u003cbr /\u003e\n  });\u003cbr /\u003e\n});\n\nNext enable middleware’s for serving generated swagger json and swagger ui by adding below code to startup.configure method\n\napp.UseSwagger();\n\napp.UseSwaggerUI(opt =\u003e\u003cbr /\u003e\n{\u003cbr /\u003e\n  opt.SwaggerEndpoint(\"/swagger/v1/swagger.json\", \"Web api documentation\");\u003cbr /\u003e  \n});\n\nNow all should go as expected, run application with ctrl+F5 or F5 and hit URL baseurl/swagger (https://localhost:44313/swagger for my demo application). \n\nIn all above document it's minimum and siplest way to enable openAPI/swagger to web api. We can also extend this documentation to more information like api description, contact details and licence info etc. To extend we documentation we need provide all these details to services.AddSwaggerGen method under Startup.ConfigureServices as \n\nservices.AddSwaggerGen(conf =\u003e\u003cbr /\u003e\n{\nconf.SwaggerDoc(\"v1\", new OpenApiInfo\u003cbr /\u003e\n{\u003cbr /\u003e\nTitle = \"Api documentation\",\u003cbr /\u003e\nVersion = \"1.0.0\",\u003cbr /\u003e\nDescription = \"Demo api for ducumentation\",\u003cbr /\u003e\nLicense = new OpenApiLicense\u003cbr /\u003e\n{\u003cbr /\u003e\nName = \"Licence name\",\u003cbr /\u003e\nUrl = new Uri(\"https://licence_Terms_URL.com\")\u003cbr /\u003e\n},\u003cbr /\u003e\nContact = new OpenApiContact\u003cbr /\u003e\n{\u003cbr /\u003e\nName = \"Surender Tanwar\",\u003cbr /\u003e\nEmail = \"tanwar.mydream3010@gmail.com\",\u003cbr /\u003e\nUrl = new Uri(\"https://github.com/Surender1987\")\u003cbr /\u003e\n}\u003cbr /\u003e\n});\u003cbr /\u003e\n});\u003cbr /\u003e\n\nAddition to above we can also use XML comments for dumenation through swagger. It will automativally produce document from XML comment. To include xml comments for documentation we have to enable xml documentation file in project \n\nRight click to solution ---\u003e Properties ---\u003e Select buld tab in left ---\u003e Under output section select checkbox forr xml documentation file ---\u003e Save with ctrl + s\n\nNext, add following code to services.AddSwaggerGen under startup.configureservices method \n\n // Set the comments path for the Swagger JSON and UI.\u003cbr /\u003e\nvar xmlFile = $\"{Assembly.GetEntryAssembly().GetName().Name}.xml\";\u003cbr /\u003e\nvar xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\u003cbr /\u003e\nconf.IncludeXmlComments(xmlPath);\u003cbr /\u003e\n                \nAdd xml comments to controller actions as example given below\n\n/// \u003csummary\u003e\u003cbr /\u003e\n/// Creates a TodoItem.\u003cbr /\u003e\n/// \u003c/summary\u003e\u003cbr /\u003e\n/// \u003cremarks\u003e\u003cbr /\u003e\n/// Sample request:\u003cbr /\u003e\n///\u003cbr /\u003e\n/// POST /Todo\u003cbr /\u003e\n/// {\u003cbr /\u003e\n/// \"id\": 1,\u003cbr /\u003e\n/// \"name\": \"Item1\",\u003cbr /\u003e\n/// \"isComplete\": true\u003cbr /\u003e\n/// }\u003cbr /\u003e\n///\u003cbr /\u003e\n/// \u003c/remarks\u003e\u003cbr /\u003e\n/// \u003cparam name=\"item\"\u003e\u003c/param\u003e\u003cbr /\u003e\n/// \u003creturns\u003eA newly created TodoItem\u003c/returns\u003e\u003cbr /\u003e\n/// \u003cresponse code=\"201\"\u003eReturns the newly created item\u003c/response\u003e\u003cbr /\u003e\n/// \u003cresponse code=\"400\"\u003eIf the item is null\u003c/response\u003e\u003cbr /\u003e\n\nThese all comments will be added to swagger UI\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurender1987%2Fwebapidocumentationwithswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurender1987%2Fwebapidocumentationwithswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurender1987%2Fwebapidocumentationwithswagger/lists"}