{"id":13429544,"url":"https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters","last_synced_at":"2025-03-16T03:31:49.565Z","repository":{"id":39873315,"uuid":"89951254","full_name":"mattfrear/Swashbuckle.AspNetCore.Filters","owner":"mattfrear","description":"A bunch of useful filters for Swashbuckle.AspNetCore","archived":false,"fork":false,"pushed_at":"2024-05-01T03:24:22.000Z","size":610,"stargazers_count":433,"open_issues_count":22,"forks_count":80,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-04T07:06:23.960Z","etag":null,"topics":["swagger","swagger-documentation","swashbuckle"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattfrear.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2017-05-01T18:35:01.000Z","updated_at":"2025-03-02T12:43:40.000Z","dependencies_parsed_at":"2023-02-06T09:00:47.724Z","dependency_job_id":"86ea74ca-bb6a-4ab6-aa81-3dba6de62c35","html_url":"https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters","commit_stats":{"total_commits":393,"total_committers":37,"mean_commits":"10.621621621621621","dds":0.2951653944020356,"last_synced_commit":"a8a769322b48615958d8ad1f09311282f99a79fc"},"previous_names":["mattfrear/swashbuckle.aspnetcore.examples"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattfrear%2FSwashbuckle.AspNetCore.Filters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattfrear%2FSwashbuckle.AspNetCore.Filters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattfrear%2FSwashbuckle.AspNetCore.Filters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattfrear%2FSwashbuckle.AspNetCore.Filters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattfrear","download_url":"https://codeload.github.com/mattfrear/Swashbuckle.AspNetCore.Filters/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243809851,"owners_count":20351407,"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":["swagger","swagger-documentation","swashbuckle"],"created_at":"2024-07-31T02:00:41.520Z","updated_at":"2025-03-16T03:31:49.223Z","avatar_url":"https://github.com/mattfrear.png","language":"C#","funding_links":[],"categories":["Frameworks, Libraries and Tools","others","C#","C\\#","框架, 库和工具","C# #"],"sub_categories":["API"],"readme":"# Swashbuckle.AspNetCore.Filters\n[![Build status](https://ci.appveyor.com/api/projects/status/l6cowxsqp2n9e4sl?svg=true)](https://ci.appveyor.com/project/mattfrear/swashbuckle-aspnetcore-examples)\n[![NuGet](https://img.shields.io/nuget/v/Swashbuckle.AspNetCore.Filters.svg)](https://www.nuget.org/packages/Swashbuckle.AspNetCore.Filters/)\n\n| :mega: Rename to Swashbuckle.AspNetCore.Filters |\n|--------------|\n| This project was formerly called Swashbuckle.AspNetCore.Examples, but it has grown from there to become a grab-bag of various filters I have created (or copied) since I started used Swashbuckle in 2015. So I have renamed it.|\n\nThis library contains a bunch of filters for [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).\n- Add example requests https://mattfrear.com/2016/01/25/generating-swagger-example-requests-with-swashbuckle/\n- Add example responses https://mattfrear.com/2015/04/21/generating-swagger-example-responses-with-swashbuckle/\n- Add security info to each operation that has an `[Authorize]` attribute, allowing you to send OAuth2 bearer tokens via Swagger-UI https://mattfrear.com/2018/07/21/add-an-authorization-header-to-your-swagger-ui-with-swashbuckle-revisited/\n- Add any old request header to all requests\n- Add any old response header to all responses\n- Add an indicator to each endpoint to show if it has an `[Authorize]` attribute (and for which policies and roles)\n\n## Table of Contents\n\n- [Changelog](#changelog)\n- [Where to get it](#where-to-get-it)\n- [What's included](#whats-included)\n  - [Request example](#request-example)\n  - [Response example](#response-example)\n  - [Security requirements filter](#security-requirements-filter)\n  - [Add a request header](#add-a-request-header)\n  - [Add a response header](#add-a-response-header)\n  - [Add Authorization to Summary](#add-authorization-to-summary)\n- [Installation](#installation)\n- [How to use](#how-to-use)\n  - [How to use - Request examples](#how-to-use---request-examples)\n  - [DO NOT USE THIS FILTER UNLESS YOU HAVE TO](#do-not-use-this-filter-unless-you-have-to)\n    - [Automatic annotation](#automatic-annotation)\n    - [Manual annotation](#manual-annotation)\n    - [List Request examples](#list-request-examples)\n  - [How to use - Response examples](#how-to-use---response-examples)\n  - [AGAIN, DO NOT USE THIS FILTER UNLESS YOU HAVE TO](#again-do-not-use-this-filter-unless-you-have-to)\n    - [Automatic annotation](#automatic-annotation-1)\n    - [Manual annotation](#manual-annotation-1)\n    - [Known issues](#known-issues)\n  - [How to use - Multiple examples](#how-to-use---multiple-examples)\n  - [How to use - Security requirements filter](#how-to-use---security-requirements-filter)\n  - [How to use - Request Header](#how-to-use---request-header)\n  - [How to use - Response headers](#how-to-use---response-headers)\n  - [How to use - Authorization summary](#how-to-use---authorization-summary)\n- [Pascal case or Camel case?](#pascal-case-or-camel-case)\n- [Render Enums as strings](#render-enums-as-strings)\n- [Advanced: Examples with Dependency injection](#advanced-examples-with-dependency-injection)\n\n## Changelog\nSee the [CHANGELOG.md](CHANGELOG.md).\n\n## Where to get it\nFrom NuGet.\n\n| Version of Swashbuckle you're using | You'll want this version of this package |\n|-------------------------------------|-----------------------------------------|\n| Swashbuckle 1.0 - 5.5 | https://www.nuget.org/packages/Swashbuckle.Examples/ |\n| Swashbuckle.AspNetCore version 1.0.0 - 2.5.0 | https://www.nuget.org/packages/Swashbuckle.AspNetCore.Examples/ |\n| Swashbuckle.AspNetCore version 3.0.0  | https://www.nuget.org/packages/Swashbuckle.AspNetCore.Filters/ |\n| Swashbuckle.AspNetCore version 4.0.0 and above | https://www.nuget.org/packages/Swashbuckle.AspNetCore.Filters/ Version \u003e= 4.5.1 |\n| Swashbuckle.AspNetCore version 5.0.0-beta and above | https://www.nuget.org/packages/Swashbuckle.AspNetCore.Filters/ Version \u003e= 5.0.0-beta |\n\n## What's included\n### Request example\n\nPopulate swagger's `paths.path.[http-verb].requestBody.content.[content-type].example` with whatever object you like.\n\nThis is great for manually testing and demoing your API as it will prepopulate the request with some useful data, so that \nwhen you click the example request in order to populate the form, instead of getting an autogenerated request like this:\n\n![autogenerated request with crappy data](https://mattfrear.files.wordpress.com/2016/01/untitled.png?w=700)\n\nYou’ll get your desired example, with useful valid data, like this:\n\n![custom request with awesome data](https://mattfrear.files.wordpress.com/2016/01/capture2.jpg?w=700)\n\nYou can see the example output in the underlying swagger.json file, which you can get to by starting your solution and \nnavigating to swagger/v1/swagger.json\n\n![swagger.json](https://mattfrear.files.wordpress.com/2016/01/capture.jpg)\n\nAs of version 5.0.0-beta, XML examples are also supported.\n\n### Response example\n\nAllows you to add custom data to the example response shown in Swagger. So instead of seeing the default boring data like so:\n\n![response with crappy data](https://mattfrear.files.wordpress.com/2015/04/response-old.png)\n\nYou'll see some more realistic data (or whatever you want):\n\n![response with awesome data](https://mattfrear.files.wordpress.com/2015/04/response-new.png?w=700\u0026h=358)\n\nAs of version 5.0.0-beta, XML examples are also supported.\n\n### Security requirements filter\n\nAdds security information to each operation so that you can send an Authorization header to your API. Useful for API endpoints that have JWT token\nauthentication. e.g.\n\n![authorization button](https://mattfrear.files.wordpress.com/2018/07/authbutton.jpg)\n\n![bearer token](https://mattfrear.files.wordpress.com/2018/07/authbuttonclicked.jpg)\n\n### Add a request header\n\nAdds any string to your request headers for all requests. I use this for adding a correlationId to all requests.\n![request header](https://mattfrear.files.wordpress.com/2018/01/header.jpg)\n\n### Add a response header\n\nAllows you to specify response headers for any operation\n![response headers](https://user-images.githubusercontent.com/169179/35051682-b8217740-fb9d-11e7-8bec-98d4b088dfa5.png)\n\n### Add Authorization to Summary\n\nIf you use the `[Authorize]` attribute  to your controller or to any actions, then (Auth) is added to the action's summary,\nalong with any specified policies or roles.\n\n![authorization](https://user-images.githubusercontent.com/169179/36599686-1d939bcc-18a8-11e8-8f81-d8706f1f0dc1.JPG)\n\n## Installation\n1. Install the [NuGet package](https://www.nuget.org/packages/Swashbuckle.AspNetCore.Filters/)\n\n2. In the _ConfigureServices_ method of _Startup.cs_, inside your `AddSwaggerGen` call, enable whichever filters you need\n\n```csharp\n// This method gets called by the runtime. Use this method to add services to the container.\npublic void ConfigureServices(IServiceCollection services)\n{\n    // Add framework services.\n    services.AddMvc();\n\n    services.AddSwaggerGen(c =\u003e\n    {\n        c.SwaggerDoc(\"v1\", new OpenApiInfo { Title = \"My API\", Version = \"v1\" });\n        \n        // [SwaggerRequestExample] \u0026 [SwaggerResponseExample]\n        // version \u003c 3.0 like this: c.OperationFilter\u003cExamplesOperationFilter\u003e(); \n        // version 3.0 like this: c.AddSwaggerExamples(services.BuildServiceProvider());\n        // version \u003e 4.0 like this:\n        c.ExampleFilters();\n        \n        c.OperationFilter\u003cAddHeaderOperationFilter\u003e(\"correlationId\", \"Correlation Id for the request\", false); // adds any string you like to the request headers - in this case, a correlation id\n        c.OperationFilter\u003cAddResponseHeadersFilter\u003e(); // [SwaggerResponseHeader]\n\n        var filePath = Path.Combine(AppContext.BaseDirectory, \"WebApi.xml\");\n        c.IncludeXmlComments(filePath); // standard Swashbuckle functionality, this needs to be before c.OperationFilter\u003cAppendAuthorizeToSummaryOperationFilter\u003e()\n\n        c.OperationFilter\u003cAppendAuthorizeToSummaryOperationFilter\u003e(); // Adds \"(Auth)\" to the summary so that you can see which endpoints have Authorization\n        // or use the generic method, e.g. c.OperationFilter\u003cAppendAuthorizeToSummaryOperationFilter\u003cMyCustomAttribute\u003e\u003e();\n\n        // add Security information to each operation for OAuth2\n        c.OperationFilter\u003cSecurityRequirementsOperationFilter\u003e();\n        // or use the generic method, e.g. c.OperationFilter\u003cSecurityRequirementsOperationFilter\u003cMyCustomAttribute\u003e\u003e();\n\n        // if you're using the SecurityRequirementsOperationFilter, you also need to tell Swashbuckle you're using OAuth2\n        c.AddSecurityDefinition(\"oauth2\", new OpenApiSecurityScheme\n        {\n            Description = \"Standard Authorization header using the Bearer scheme. Example: \\\"bearer {token}\\\"\",\n            In = ParameterLocation.Header,\n            Name = \"Authorization\",\n            Type = SecuritySchemeType.ApiKey\n        });\n    });\n}\n```\n\n3. If you want to use the Request and Response example filters (and have called `c.ExampleFilters()` above), then you MUST also call\n```csharp\n    services.AddSwaggerExamplesFromAssemblyOf\u003cMyExample\u003e();\n```\nor\n```csharp\n    services.AddSwaggerExamplesFromAssemblyOf(typeof(MyExample));\n```\nor\n```csharp\n    services.AddSwaggerExamplesFromAssemblies(Assembly.GetEntryAssembly());\n```\nThis will register your examples with the ServiceProvider.\n\n### Serialize Swagger in the 2.0 format\nThere are two ways to tell Swashbuckle.AspNetCore to output the swagger.json in the legacy Swagger 2.0 format:\n```csharp\napp.UseSwagger(c =\u003e c.SerializeAsV2 = true);\n\n// OR\n\nservices.Configure\u003cSwaggerOptions\u003e(c =\u003e c.SerializeAsV2 = true);\n```\nIf you want to SerializeAsV2 and you're using my Request example filter then you must call `services.Configure\u003cSwaggerOptions\u003e(c =\u003e c.SerializeAsV2 = true);`.\n\n## How to use\n\n### How to use - Request examples\n\n### DO NOT USE THIS FILTER UNLESS YOU HAVE TO\nSince May 2018, Swashbuckle.AspNetCore supports adding examples via XML comments:\n\n```csharp\npublic class Product\n{\n    /// \u003csummary\u003e\n    /// The name of the product\n    /// \u003c/summary\u003e\n    /// \u003cexample\u003eMen's basketball shoes\u003c/example\u003e\n    public string Name { get; set; }\n```\n\nThis works for request examples and response examples, and it even works for example querystring and route parameters, i.e. on GET requests!\n\nExample in a querystring on GET:\n\n![example on querystring](https://user-images.githubusercontent.com/169179/79851411-6282a780-8419-11ea-853f-318d1443e7a9.png)\n\nExample request body in a POST:\n\n![example request body](https://mattfrear.files.wordpress.com/2020/04/request.png)\n\nExample response:\n\n![example response](https://mattfrear.files.wordpress.com/2020/04/post.png)\n\nAnd soon (April 2020, once [my Swashbuckle.AspNetCore PR](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/1629) has been released) you'll be able to add examples for primitive types on the querystring too, e.g.\n\n```csharp\n/// \u003cparam name=\"id\" example=\"123\"\u003eThe product id\u003c/param\u003e\n[HttpGet(\"{id}\")]\npublic Product GetById(int id)\n```\n\nSee [the instructions on Swashbuckle.AspNetCore's Readme](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments).\n\nTherefore, I recommend that you move away from using my `ExamplesOperationFilter`. Personally, I don't use it any more [and would like to deprecate it](https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters/issues/108).\n\nHowever, you may have a use case where XML comments doesn't work for you, e.g.\n- You want to generate examples at runtime not design time\n- You need XML request examples (not JSON)\n- You want examples to be added to the schema under the path, rather than the schema under the component\n- Some other ReDoc issue which I don't understand as I don't use ReDoc...\n\nIn which case, read on...\n\n#### Automatic annotation\nVersion 4.0 and above supports automatic annotation.\n\nLet's say you have a controller action which takes some input from the body, in this case a `DeliveryOptionsSearchModel`:\n```csharp\n[HttpPost]\npublic async Task\u003cIHttpActionResult\u003e DeliveryOptionsForAddress([FromBody]DeliveryOptionsSearchModel search)\n```\nThen all you need to do is implement `IExamplesProvider\u003cDeliveryOptionsSearchModel\u003e`:\n```csharp\npublic class DeliveryOptionsSearchModelExample : IExamplesProvider\u003cDeliveryOptionsSearchModel\u003e\n{\n    public DeliveryOptionsSearchModel GetExamples()\n    {\n        return new DeliveryOptionsSearchModel\n        {\n            Lang = \"en-GB\",\n            Currency = \"GBP\",\n            Address = new AddressModel\n            {\n                Address1 = \"1 Gwalior Road\",\n                Locality = \"London\",\n                Country = \"GB\",\n                PostalCode = \"SW15 1NP\"\n            }\n        };\n    }\n```\nAnd that's it.\n\n#### Manual annotation\nAlternatively, if you want to be more explicit, you can use the `SwaggerRequestExample` attribute. This is how it was done in versions 1.0 - 3.0. Any manual annotations will override automatic annotations.\n\nDecorate your controller methods with the included `SwaggerRequestExample` attribute:\n\n```csharp\n[HttpPost]\n[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]\npublic async Task\u003cIHttpActionResult\u003e DeliveryOptionsForAddress([FromBody]DeliveryOptionsSearchModel search)\n```\n\nNow implement a `IExamplesProvider\u003cT\u003e`, in this case via a DeliveryOptionsSearchModelExample which will generate the example data. It should return the type you specified when you specified the `[SwaggerRequestExample]`.\n\t\n```csharp\npublic class DeliveryOptionsSearchModelExample : IExamplesProvider\u003cDeliveryOptionsSearchModel\u003e\n{\n    public DeliveryOptionsSearchModel GetExamples()\n    {\n        return new DeliveryOptionsSearchModel\n        {\n            Lang = \"en-GB\",\n            Currency = \"GBP\",\n            Address = new AddressModel\n            {\n                Address1 = \"1 Gwalior Road\",\n                Locality = \"London\",\n                Country = \"GB\",\n                PostalCode = \"SW15 1NP\"\n            },\n            Items = new[]\n            {\n                new ItemModel\n                {\n                    ItemId = \"ABCD\",\n                    ItemType = ItemType.Product,\n                    Price = 20,\n                    Quantity = 1,\n                    RestrictedCountries = new[] { \"US\" }\n                }\n            }\n        };\n    }\n```\n\nIn the Swagger document, this will populate the operation's requestBody content type example property. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#mediaTypeObject\n\nHere's what the OpenApi 3.0 spec says about it:\n\nField Name | Type | Description\n---|:---:|---\nexample | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` object is mutually exclusive of the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.\n\n#### List Request examples\nAs of version 2.4, `List\u003cT\u003e` request examples are supported. For any `List\u003cT\u003e` in the request, you may define a SwaggerRequestExample for `T`. \nYour IExamplesProvider should only return a single `T` and not a `List\u003cT\u003e`.\nWorking example:\n\n```csharp\n[SwaggerRequestExample(typeof(PeopleRequest), typeof(ListPeopleRequestExample))]\npublic IEnumerable\u003cPersonResponse\u003e GetPersonList([FromBody]List\u003cPeopleRequest\u003e peopleRequest)\n{\n\n// and then:\n\npublic class ListPeopleRequestExample : IExamplesProvider\u003cPeopleRequest\u003e\n{\n    public PeopleRequest GetExamples()\n    {\n        return new PeopleRequest { Title = Title.Mr, Age = 24, FirstName = \"Dave in a list\", Income = null };\n    }\n}\n\n```\n\n### How to use - Response examples\n### AGAIN, DO NOT USE THIS FILTER UNLESS YOU HAVE TO\nI repeat my earlier assertion - Since May 2018, Swashbuckle.AspNetCore supports adding examples via XML comments.\n\n[See above for instructions](#do-not-use-this-filter-unless-you-have-to)\n\nIf you still want to use it, read on...\n\n#### Automatic annotation\nVersion 4.0 supports automatic annotation.\nIf it's obvious which type your action returns, then no `ProducesResponseType` or `SwaggerResponse` attributes need to be specified, e.g.\n```csharp\npublic async Task\u003cActionResult\u003cIEnumerable\u003cCountry\u003e\u003e\u003e Get(string lang)\n// or public ActionResult\u003cIEnumerable\u003cCountry\u003e\u003e Get(string lang)\n// or public IEnumerable\u003cCountry\u003e Get(string lang)\n```\n\n#### Manual annotation\nAlternatively, if you want to be more explicit, you can use the `SwaggerResponseExample` attribute. This is how it was done in versions 1.0 - 3.0. Any manual annotations will override automatic annotations.\n\nDecorate your methods with the new SwaggerResponseExample attribute:\n```csharp\n[SwaggerResponse(200, \"The list of countries\", typeof(IEnumerable\u003cCountry\u003e))]\n// or, like this [ProducesResponseType(typeof(IEnumerable\u003cCountry\u003e), 200)]\n[SwaggerResponseExample(200, typeof(CountryExamples))]\n[SwaggerResponse(400, type: typeof(IEnumerable\u003cErrorResource\u003e))]\npublic async Task\u003cHttpResponseMessage\u003e Get(string lang)\n```\nFor manual annotation implement `IExamplesProvider\u003cT\u003e` to generate the example data\n\n```csharp\t\npublic class CountryExamples : IExamplesProvider\u003cList\u003cCountry\u003e\u003e\n{\n    public List\u003cCountry\u003e GetExamples()\n    {\n        return new List\u003cCountry\u003e\n        {\n            new Country { Code = \"AA\", Name = \"Test Country\" },\n            new Country { Code = \"BB\", Name = \"And another\" }\n        };\n    }\n}\n```\n\nIn the Swagger document, this will populate the operation's responses content [example object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject).\nThe spec for this says:\n\nField Pattern | Type | Description\n---|:---:|---\nexample | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` object is mutually exclusive of the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.\n\nExample response for application/json mimetype of a Pet data type:\n\n```js\n \"responses\": {\n          \"200\": {\n            \"description\": \"Success\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"$ref\": \"#/components/schemas/Pet\"\n                },\n                \"example\": \"{\\r\\n  \\\"name\\\": \\\"Lassie\\\",\\r\\n  \\\"type\\\": \\\"Dog\\\",\\r\\n  \\\"color\\\": \\\"Black\\\",\\r\\n  \\\"gender\\\": \\\"Femail\\\",\\r\\n  \\\"breed\\\": \\\"Collie\\\" \\r\\n}\"\n              },\n```\n\n\n#### Known issues\n- Request examples are not shown for querystring parameters (i.e. HTTP GET requests, or for querystring parameters for POST, PUT etc methods). Request examples will only be shown in request body. \nYou can use Swashbuckle.AspNetCore's built-in XML comments to add examples for primitive types.\n\n### How to use - Multiple examples\n\nSometimes more than a single example are desirable for an API. In this case you can use `IMultipleExamplesProvider\u003cT\u003e` rather than `IExamplesProvider\u003cT\u003e` to return multiple examples. The example provider class is still located in the same way (automatic or manual annotation), but the `GetExamples()` call returns an enumerated list of examples along with their name and optional summary. To reduce boilerplate, it is recommended to use `yield return` for each example value. Every returned `SwaggerExample\u003cT\u003e` should have different value of `Name` property.\n\n```csharp\npublic class DeliveryOptionsSearchModelExample : IMultipleExamplesProvider\u003cDeliveryOptionsSearchModel\u003e\n{\n    public IEnumerable\u003cSwaggerExample\u003cDeliveryOptionsSearchModel\u003e\u003e GetExamples()\n    {\n        // An example without a summary.\n        yield return SwaggerExample.Create(\n            \"Great Britain\",\n            \"Here's an optional description\" // optional description - Markdown is supported\n            new DeliveryOptionsSearchModel\n            {\n                Lang = \"en-GB\",\n                Currency = \"GBP\",\n                Address = new AddressModel\n                {\n                    Address1 = \"1 Gwalior Road\",\n                    Locality = \"London\",\n                    Country = \"GB\",\n                    PostalCode = \"SW15 1NP\"\n                }\n            }\n        );\n\n        // An example with a summary.\n        yield return SwaggerExample.Create(\n            \"United States\",\n            \"A minor former colony of Great Britain\",\n            new DeliveryOptionsSearchModel\n            {\n                Lang = \"en-US\",\n                Currency = \"USD\",\n                Address = new AddressModel\n                {\n                    Address1 = \"123 Main Street\",\n                    Locality = \"New York\",\n                    Country = \"US\",\n                    PostalCode = \"10001\"\n                }\n            },\n        );\n    }\n```\n\nNote that UIs may choose to display the summary in different ways; in ReDoc, for example, the summary (if present) replaces the name in the UI.\n\n\n### How to use - Security requirements filter\n\nFirst you need to already have OAuth2 configured correctly, and some of your controllers and actions locked down with the `[Authorize]` attribute. \nN.B. globally registered Authorization filters are not detected.\n\nThen you need to tell Swagger that you're using OAuth2, as shown in the Installation section above:\n```csharp\n    services.AddSwaggerGen(c =\u003e\n    {\n        c.AddSecurityDefinition(\"oauth2\", new OpenApiSecurityScheme\n        {\n            Description = \"Standard Authorization header using the Bearer scheme. Example: \\\"bearer {token}\\\"\",\n            In = ParameterLocation.Header,\n            Name = \"Authorization\",\n            Type = SecuritySchemeType.ApiKey\n        });\n```\nThis adds a securityDefinition to the bottom of the Swagger document, which Swagger-UI renders as an \"Authorize\" button, which when clicked brings up the Authorize dialog box shown above.\n\nThen, when you enable the SecurityRequirementsOperationFilter:\n```csharp\n\t// add Security information to each operation for OAuth2\n\tc.OperationFilter\u003cSecurityRequirementsOperationFilter\u003e();\n```\nIt adds a security property to each operation, which renders in Swagger-UI as a padlock next to the operation:\n![locked down actions](https://mattfrear.files.wordpress.com/2018/07/securityonaction.jpg)\n\nBy default, the SecurityRequirementsOperationFilter also adds 401 and 403 to each operation that has `[Authorize]` on it:\n![401 and 403](https://mattfrear.files.wordpress.com/2018/07/401-403.jpg)\n\nIf you don't want to do that you can pass false when you configure it:\n\n```csharp\n\tc.OperationFilter\u003cSecurityRequirementsOperationFilter\u003e(false);\n```\n\n### How to use - Request Header\nWhen you enable the filter in your `Startup.cs`, as per the Installation section above, you can specify the name (string)\nand description (string) of the new header parameter, as well as whether it is required or not (bool).\nThis will add the input box to *every* controller action.\n\n### How to use - Response headers\n\nSpecify one or more `[SwaggerResponseHeader]` attributes on your controller action. \nYou can specify the status code (int), header name (string), type (string), description (string) and format (string). \nSee the OpenAPI Specification spec for information on DataTypes: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes\n```csharp\n[SwaggerResponseHeader(StatusCodes.Status200OK, \"Location\", \"string\", \"Location of the newly created resource\")]\n[SwaggerResponseHeader(200, \"ETag\", \"string\", \"An ETag of the resource\")]\n[SwaggerResponseHeader(429, \"Retry-After\", \"integer\", \"Indicates how long to wait before making a new request.\", \"int32\")]\n[SwaggerResponseHeader(new int[] { 200, 401, 403, 404 }, \"CustomHeader\", \"string\", \"A custom header\")]\npublic IHttpActionResult GetPerson(PersonRequest personRequest)\n{\n```\n\n### How to use - Authorization summary\nSpecify `[Authorization]` headers on either a Controller:\n```csharp\n[Authorize]\npublic class ValuesController : Controller\n```\nor on an action:\n```csharp\n[Authorize(\"Customer\")]\npublic PersonResponse GetPerson([FromBody]PersonRequest personRequest)\n```\nYou can optionally specify policies `[Authorize(\"Customer\")]` or roles `[Authorize(Roles = \"Customer\")]` and they will be added to the Summary too.\n\n## Pascal case or Camel case?\n~~The default is camelCase. If you want PascalCase you can pass in a `DefaultContractResolver` like so:\n`[SwaggerResponseExample(200, typeof(PersonResponseExample), typeof(DefaultContractResolver))]`~~\n\nThe above is no longer supported - it will output Examples using whichever JSON serializer your controllers are configured with\nin `services.AddControllers()`.\n\n### Minimal APIs\nIf you're using .NET 5 and above, we now default to use `System.Text.Json.JsonSerializerDefaults.Web` when rendering examples,\nwhich means you'll get camelCase. PascalCase is not supported.\n\n## Render Enums as strings\n~~By default `enum`s will output their integer values. If you want to output strings you can pass in a `StringEnumConverter` like so:\n`[SwaggerResponseExample(200, typeof(PersonResponseExample), jsonConverter: typeof(StringEnumConverter))]`~~\n\nThe above is no longer supported - it will output Examples using whichever JSON serializer your controllers are configured with\nin `services.AddControllers()`.\n\n\n## Advanced: Examples with Dependency injection\n\nIf for some reason you need to have examples with DI (for example, to read them from a database), you can use constructor injection:\n\n```csharp\ninternal class PersonRequestExample : IExamplesProvider\n{\n    private readonly IHostingEnvironment _env;\n\n    public PersonRequestExample(IHostingEnvironment env)\n    {\n        _env = env;\n    }\n    public object GetExamples()\n    {\n        return new PersonRequest { Age = 24, FirstName = _env.IsDevelopment() ? \"Development\" : \"Production\", Income = null };\n    }\n}\n```\nThen, you should register the Swagger examples via the extension methods:\n```csharp\nservices.AddSwaggerExamplesFromAssemblyOf\u003cPersonRequestExample\u003e();\n```\nor\n```csharp\nservices.AddSwaggerExamplesFromAssemblyOf(typeof(PersonRequestExample));\n```\nor\n```csharp\nservices.AddSwaggerExamplesFromAssemblies(Assembly.GetEntryAssembly());\n```\nIf you are using `services.AddSwaggerExamples()`, then you would have to manually register your `IExamplesProvider` class:\n```csharp\nservices.AddSingleton\u003cPersonRequestExample\u003e();\n```\nThe `FromAssemblyOf\u003cT\u003e` extension method is the recommended approach.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattfrear%2FSwashbuckle.AspNetCore.Filters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattfrear%2FSwashbuckle.AspNetCore.Filters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattfrear%2FSwashbuckle.AspNetCore.Filters/lists"}