{"id":19998030,"url":"https://github.com/abelsilva/swaggerwcf","last_synced_at":"2025-04-13T04:59:35.931Z","repository":{"id":1637867,"uuid":"36717753","full_name":"abelsilva/swaggerwcf","owner":"abelsilva","description":"Swagger for WCF","archived":false,"fork":false,"pushed_at":"2022-06-22T18:07:34.000Z","size":5821,"stargazers_count":134,"open_issues_count":52,"forks_count":97,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-13T04:59:29.585Z","etag":null,"topics":["csharp","swagger","wcf"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abelsilva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-02T08:02:50.000Z","updated_at":"2025-04-08T07:38:53.000Z","dependencies_parsed_at":"2022-08-06T11:00:21.628Z","dependency_job_id":null,"html_url":"https://github.com/abelsilva/swaggerwcf","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abelsilva%2Fswaggerwcf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abelsilva%2Fswaggerwcf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abelsilva%2Fswaggerwcf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abelsilva%2Fswaggerwcf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abelsilva","download_url":"https://codeload.github.com/abelsilva/swaggerwcf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665756,"owners_count":21142123,"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":["csharp","swagger","wcf"],"created_at":"2024-11-13T05:07:06.257Z","updated_at":"2025-04-13T04:59:35.902Z","avatar_url":"https://github.com/abelsilva.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"left\"\u003e\nSwaggerWcf\u0026nbsp;\u003ca href=\"https://www.nuget.org/packages/SwaggerWcf\"\u003e\n        \u003cimg src=\"http://img.shields.io/nuget/v/SwaggerWcf.svg?style=flat\" alt=\"nuget status\"\u003e\n    \u003c/a\u003e\n\u003c/h1\u003e\n\nGenerates [Swagger](http://swagger.io/) (2.0) for WCF services and also provides [swagger-ui](https://github.com/swagger-api/swagger-ui).\n\nWith an API described in Swagger you can use multiple Swagger tools like client generators, see [swagger-codegen](https://github.com/swagger-api/swagger-codegen) for more details.\n\nThis project has started as a fork from [superstator/Swaggeratr](https://github.com/superstator/Swaggeratr) to implement version 2.0 of Swagger.\n\n## Getting Started\n\n### Step 1: Install SwaggerWcf package\n\n```\n\nInstall-Package SwaggerWcf\n\n```\n\n### Step 2: Configure WCF\n#### ASP.NET\n\nAdd the route in the `Application_Start` method inside `Global.asax`\n\n```csharp\n\nprotected void Application_Start(object sender, EventArgs e)\n{\n    // [.......]\n    \n    RouteTable.Routes.Add(new ServiceRoute(\"api-docs\", new WebServiceHostFactory(), typeof(SwaggerWcfEndpoint)));\n}\n\n```\n\nNote: You might need to add a reference to `System.ServiceModel.Activation`\n\nEdit `Web.config` and add the following (if it doesn't exist yet) inside the `system.serviceModel` block\n\n```xml\n\n\u003cserviceHostingEnvironment aspNetCompatibilityEnabled=\"true\" multipleSiteBindingsEnabled=\"true\"/\u003e\n\n```\n\nEdit again `Web.config` and add the following (if it doesn't exist yet) inside the `system.webServer` block\n\n```xml\n\n\u003cmodules runAllManagedModulesForAllRequests=\"true\"/\u003e\n\n```\n#### Self Hosted\nAdd an endpoint to your App.config file.\n```xml\n\u003cservices\u003e\n  \u003cservice name=\"SwaggerWcf.SwaggerWcfEndpoint\"\u003e\n    \u003cendpoint address=\"http://localhost/docs\" binding=\"webHttpBinding\" contract=\"SwaggerWcf.ISwaggerWcfEndpoint\" /\u003e\n  \u003c/service\u003e\n\u003c/services\u003e\n```\nCreate a WebServiceHost\n```csharp\nvar swaggerHost = new WebServiceHost(typeof(SwaggerWcfEndpoint));\nswaggerHost.Open();\n```\n\n### Step 3: Optionaly configure WCF response auto types\n\nAdd the following to your config file.\nThis will allow the WCF service to accept requests and send replies based on the `Content-Type` headers.\n\n```xml\n\n\u003csystem.serviceModel\u003e\n  \u003cbehaviors\u003e\n    \u003cendpointBehaviors\u003e\n      \u003cbehavior\u003e\n        \u003cwebHttp automaticFormatSelectionEnabled=\"true\" /\u003e\n      \u003c/behavior\u003e\n    \u003c/endpointBehaviors\u003e\n    \u003c!-- [.......] --\u003e\n  \u003c/behaviors\u003e\n\u003c/system.serviceModel\u003e\n  \n```\n\n### Step 4: Configure WCF services general information\n#### Configure via config file\nAdd the following to your config file and change the values accordingly\n\n```xml\n\u003cconfigSections\u003e\n  \u003csection name=\"swaggerwcf\" type=\"SwaggerWcf.Configuration.SwaggerWcfSection, SwaggerWcf\" /\u003e\n\u003c/configSections\u003e\n\n\u003cswaggerwcf\u003e\n  \u003ctags\u003e\n    \u003ctag name=\"LowPerformance\" visible=\"false\" /\u003e\n  \u003c/tags\u003e\n  \u003csettings\u003e\n    \u003csetting name=\"InfoDescription\" value=\"Sample Service to test SwaggerWCF\" /\u003e\n    \u003csetting name=\"InfoVersion\" value=\"0.0.1\" /\u003e\n    \u003csetting name=\"InfoTermsOfService\" value=\"Terms of Service\" /\u003e\n    \u003csetting name=\"InfoTitle\" value=\"SampleService\" /\u003e\n    \u003csetting name=\"InfoContactName\" value=\"Abel Silva\" /\u003e\n    \u003csetting name=\"InfoContactUrl\" value=\"http://github.com/abelsilva\" /\u003e\n    \u003csetting name=\"InfoContactEmail\" value=\"no@e.mail\" /\u003e\n    \u003csetting name=\"InfoLicenseUrl\" value=\"https://github.com/abelsilva/SwaggerWCF/blob/master/LICENSE\" /\u003e\n    \u003csetting name=\"InfoLicenseName\" value=\"Apache License\" /\u003e\n  \u003c/settings\u003e\n\u003c/swaggerwcf\u003e\n```\n\nNotes:\n* make sure the `configSections` block is the first child of `configuration`\n* `tags` will be described further down\n\n#### Configure via code\nConfigure the base properties via code. New: You can add security settings to your api (see also the new Security-Methodattribute)\n\n```csharp\nvar info = new Info\n{\nDescription = \"Sample Service to test SwaggerWCF\",\nVersion = \"0.0.1\"\n// etc\n};\n\nvar security = new SecurityDefinitions\n{\n  {\n    \"api-gateway\", new SecurityAuthorization\n    {\n      Type = \"oauth2\",\n      Name = \"api-gateway\",\n      Description = \"Forces authentication with credentials via an api gateway\",\n      Flow = \"password\",\n      Scopes = new Dictionary\u003cstring, string=\"\"\u003e\n      {\n          { \"author\", \"use author scope\"},\n          { \"admin\", \"use admin scope\"},\n      },\n      AuthorizationUrl = \"http://yourapi.net/oauth/token\"\n    }\n  }\n};\n\nSwaggerWcfEndpoint.Configure(info, security);\n```\n\n### Step 5: Decorate WCF services interfaces\n\nFor each method, configure the `WebInvoke` or `WebGet` attribute, and add a `SwaggerWcfPath` attribute.\n\n```csharp\n\n[ServiceContract]\npublic interface IStore\n{\n    [SwaggerWcfPath(\"Create book\", \"Create a book on the store\")]\n    [WebInvoke(UriTemplate = \"/books\",\n        BodyStyle = WebMessageBodyStyle.Bare,\n        Method = \"POST\",\n        RequestFormat = WebMessageFormat.Json,\n        ResponseFormat = WebMessageFormat.Json)]\n    [OperationContract]\n    Book CreateBook(Book value);\n    \n    // [.......]\n}\n\n```\n\n### Step 6: Decorate WCF services class\n\nAdd the `SwaggerWcf` and `AspNetCompatibilityRequirements` attributes to the class providing the base path for the service (the same as used in step 2).\nOptinally, for each method, add the `SwaggerWcfTag` to categorize the method and the `SwaggerWcfResponse` for each possible response from the service.\n\n```csharp\n\n[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]\n[SwaggerWcf(\"/v1/rest\")]\npublic class BookStore : IStore\n{\n    [SwaggerWcfTag(\"Books\")]\n    [SwaggerWcfResponse(HttpStatusCode.Created, \"Book created, value in the response body with id updated\")]\n    [SwaggerWcfResponse(HttpStatusCode.BadRequest, \"Bad request\", true)]\n    [SwaggerWcfResponse(HttpStatusCode.InternalServerError,\n        \"Internal error (can be forced using ERROR_500 as book title)\", true)]\n    public Book CreateBook(Book value)\n    {\n        // [.......]\n    }\n    \n    // [.......]\n}\n\n```\n\n### Step 7: Decorate data types used in WCF services\n\n```csharp\n\n[DataContract(Name = \"book\")]\n[Description(\"Book with title, first publish date, author and language\")]\n[SwaggerWcfDefinition(ExternalDocsUrl = \"http://en.wikipedia.org/wiki/Book\", ExternalDocsDescription = \"Description of a book\")]\npublic class Book\n{\n    [DataMember(Name = \"id\")]\n    [Description(\"Book ID\")]\n    public string Id { get; set; }\n\n    // [.......]\n}\n\n```\n\nNote: make sure you add at least the `DataContract` and `DataMember` attributes in classes and properties\n\n## Attributes\n\n| Attribute                | Used in                                    | Description                            | Options                                                                                             |\n| ------------------------ |------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `SwaggerWcf`             | `Class`, `Interface`                       | Enable parsing WCF service             | `ServicePath`                                                                                       |\n| `SwaggerWcfHidden`       | `Class`, `Method`, `Property`, `Parameter` | Hide element from Swagger              |                                                                                                     |\n| `SwaggerWcfTag`          | `Class`, `Method`, `Property`, `Parameter` | Add a tag to an element                | `TagName`, `HideFromSpec`                                                                           |\n| `SwaggerWcfHeader`       | `Method`                                   | Configure method HTTP headers          | `Name`, `Required`, `Description`, `DefaultValue`                                                   |\n| `SwaggerWcfPath`         | `Method`                                   | Configure a method in Swagger          | `Summary`, `Description`, `OperationId`, `ExternalDocsDescription`, `ExternalDocsUrl`, `Deprecated` |\n| `SwaggerWcfParameter`    | `Parameter`                                | Configure method parameters            | `Required`, `Description`, `ParameterType`                                                          |\n| `SwaggerWcfProperty`     | `Property`                                 | Configure property parameters          | `Required`, `Description`, `Minimum`, `Maximum`, `Default`, ...                                     |\n| `SwaggerWcfResponse`     | `Method`                                   | Configure method return value          | `Code`, `Description`, `EmptyResponseOverride`, `Headers`                                           |\n| `SwaggerWcfDefinition`   | `Class`                                    | Configure a data type                  | `ExternalDocsDescription`, `ExternalDocsUrl`                                                        |\n| `SwaggerWcfReturnType`   | `Method`                                   | Override method return type            | `ReturnType`                                                                                        |\n| `SwaggerWcfContentTypes` | `Method`                                   | Override consume/produce content-types | `ConsumeTypes`, `ProduceTypes`                                                                      |\n| `SwaggerWcfSecurity`     | `Method`                                   | Add security background to this method | `SecurityDefinitionName`, `params Scopes`                                                           |\n\n\n## Tags\n\nTags are used to create categories in Swagger UI.\n\nIn SwaggerWcf they can also be used to hide or show elements from the Swagger output using the configuration file.\n\nUsing the configuration from step 4, any elements with the tag `LowPerformance` will be hidden from Swagger.\n\nWhen a `SwaggerWcfTag` is added to an element, it may be configured with `HideFromSpec`.\nThis will prevent this tag to be displayed in the Swagger output.\n\nWhen combined with `SwaggerWcfHidden`, if the tag has the value `visible` as `true` in `web.config` file, the element will be visible\n\n## Query Parameter\n\nTo specify query parameters to a function you may use the following syntax\n\n```csharp\n[WebGet(UriTemplate = \"/books?filter={filter}\", BodyStyle = WebMessageBodyStyle.Bare)]\nBook[] ReadBooks(string filter = null);\n```\n\n## Optional Parameters\n\nTo specify a paramter as optional for swagger-ui provide a default value for the parameter on the interface.\n```csharp\npublic string Foo(string bar = null);\n```\n\n## Optional Properties\n\nTo mark a property as optional or required, use the `IsRequired` parameter on the `DataMember` attribute.\n\n\n## TODO\n\n* Add some options to configuration in `Web.config`\n* Tests\n\n## How to Improve It\n\nFork this project [abelsilva/swaggerwcf](https://github.com/abelsilva/swaggerwcf) and submit pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabelsilva%2Fswaggerwcf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabelsilva%2Fswaggerwcf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabelsilva%2Fswaggerwcf/lists"}