Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abelsilva/swaggerwcf
Swagger for WCF
https://github.com/abelsilva/swaggerwcf
csharp swagger wcf
Last synced: 1 day ago
JSON representation
Swagger for WCF
- Host: GitHub
- URL: https://github.com/abelsilva/swaggerwcf
- Owner: abelsilva
- License: apache-2.0
- Created: 2015-06-02T08:02:50.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-06-22T18:07:34.000Z (over 2 years ago)
- Last Synced: 2024-04-30T07:23:34.789Z (7 months ago)
- Topics: csharp, swagger, wcf
- Language: C#
- Size: 5.55 MB
- Stars: 132
- Watchers: 15
- Forks: 92
- Open Issues: 52
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
SwaggerWcf
Generates [Swagger](http://swagger.io/) (2.0) for WCF services and also provides [swagger-ui](https://github.com/swagger-api/swagger-ui).
With 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.
This project has started as a fork from [superstator/Swaggeratr](https://github.com/superstator/Swaggeratr) to implement version 2.0 of Swagger.
## Getting Started
### Step 1: Install SwaggerWcf package
```
Install-Package SwaggerWcf
```
### Step 2: Configure WCF
#### ASP.NET
Add the route in the `Application_Start` method inside `Global.asax`
```csharp
protected void Application_Start(object sender, EventArgs e)
{
// [.......]
RouteTable.Routes.Add(new ServiceRoute("api-docs", new WebServiceHostFactory(), typeof(SwaggerWcfEndpoint)));
}
```
Note: You might need to add a reference to `System.ServiceModel.Activation`
Edit `Web.config` and add the following (if it doesn't exist yet) inside the `system.serviceModel` block
```xml
```
Edit again `Web.config` and add the following (if it doesn't exist yet) inside the `system.webServer` block
```xml
```
#### Self Hosted
Add an endpoint to your App.config file.
```xml
```
Create a WebServiceHost
```csharp
var swaggerHost = new WebServiceHost(typeof(SwaggerWcfEndpoint));
swaggerHost.Open();
```
### Step 3: Optionaly configure WCF response auto types
Add the following to your config file.
This will allow the WCF service to accept requests and send replies based on the `Content-Type` headers.
```xml
```
### Step 4: Configure WCF services general information
#### Configure via config file
Add the following to your config file and change the values accordingly
```xml
```
Notes:
* make sure the `configSections` block is the first child of `configuration`
* `tags` will be described further down
#### Configure via code
Configure the base properties via code. New: You can add security settings to your api (see also the new Security-Methodattribute)
```csharp
var info = new Info
{
Description = "Sample Service to test SwaggerWCF",
Version = "0.0.1"
// etc
};
var security = new SecurityDefinitions
{
{
"api-gateway", new SecurityAuthorization
{
Type = "oauth2",
Name = "api-gateway",
Description = "Forces authentication with credentials via an api gateway",
Flow = "password",
Scopes = new Dictionary
{
{ "author", "use author scope"},
{ "admin", "use admin scope"},
},
AuthorizationUrl = "http://yourapi.net/oauth/token"
}
}
};
SwaggerWcfEndpoint.Configure(info, security);
```
### Step 5: Decorate WCF services interfaces
For each method, configure the `WebInvoke` or `WebGet` attribute, and add a `SwaggerWcfPath` attribute.
```csharp
[ServiceContract]
public interface IStore
{
[SwaggerWcfPath("Create book", "Create a book on the store")]
[WebInvoke(UriTemplate = "/books",
BodyStyle = WebMessageBodyStyle.Bare,
Method = "POST",
RequestFormat = WebMessageFormat.Json,
ResponseFormat = WebMessageFormat.Json)]
[OperationContract]
Book CreateBook(Book value);
// [.......]
}
```
### Step 6: Decorate WCF services class
Add the `SwaggerWcf` and `AspNetCompatibilityRequirements` attributes to the class providing the base path for the service (the same as used in step 2).
Optinally, for each method, add the `SwaggerWcfTag` to categorize the method and the `SwaggerWcfResponse` for each possible response from the service.
```csharp
[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]
[SwaggerWcf("/v1/rest")]
public class BookStore : IStore
{
[SwaggerWcfTag("Books")]
[SwaggerWcfResponse(HttpStatusCode.Created, "Book created, value in the response body with id updated")]
[SwaggerWcfResponse(HttpStatusCode.BadRequest, "Bad request", true)]
[SwaggerWcfResponse(HttpStatusCode.InternalServerError,
"Internal error (can be forced using ERROR_500 as book title)", true)]
public Book CreateBook(Book value)
{
// [.......]
}
// [.......]
}
```
### Step 7: Decorate data types used in WCF services
```csharp
[DataContract(Name = "book")]
[Description("Book with title, first publish date, author and language")]
[SwaggerWcfDefinition(ExternalDocsUrl = "http://en.wikipedia.org/wiki/Book", ExternalDocsDescription = "Description of a book")]
public class Book
{
[DataMember(Name = "id")]
[Description("Book ID")]
public string Id { get; set; }
// [.......]
}
```
Note: make sure you add at least the `DataContract` and `DataMember` attributes in classes and properties
## Attributes
| Attribute | Used in | Description | Options |
| ------------------------ |------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `SwaggerWcf` | `Class`, `Interface` | Enable parsing WCF service | `ServicePath` |
| `SwaggerWcfHidden` | `Class`, `Method`, `Property`, `Parameter` | Hide element from Swagger | |
| `SwaggerWcfTag` | `Class`, `Method`, `Property`, `Parameter` | Add a tag to an element | `TagName`, `HideFromSpec` |
| `SwaggerWcfHeader` | `Method` | Configure method HTTP headers | `Name`, `Required`, `Description`, `DefaultValue` |
| `SwaggerWcfPath` | `Method` | Configure a method in Swagger | `Summary`, `Description`, `OperationId`, `ExternalDocsDescription`, `ExternalDocsUrl`, `Deprecated` |
| `SwaggerWcfParameter` | `Parameter` | Configure method parameters | `Required`, `Description`, `ParameterType` |
| `SwaggerWcfProperty` | `Property` | Configure property parameters | `Required`, `Description`, `Minimum`, `Maximum`, `Default`, ... |
| `SwaggerWcfResponse` | `Method` | Configure method return value | `Code`, `Description`, `EmptyResponseOverride`, `Headers` |
| `SwaggerWcfDefinition` | `Class` | Configure a data type | `ExternalDocsDescription`, `ExternalDocsUrl` |
| `SwaggerWcfReturnType` | `Method` | Override method return type | `ReturnType` |
| `SwaggerWcfContentTypes` | `Method` | Override consume/produce content-types | `ConsumeTypes`, `ProduceTypes` |
| `SwaggerWcfSecurity` | `Method` | Add security background to this method | `SecurityDefinitionName`, `params Scopes` |
## Tags
Tags are used to create categories in Swagger UI.
In SwaggerWcf they can also be used to hide or show elements from the Swagger output using the configuration file.
Using the configuration from step 4, any elements with the tag `LowPerformance` will be hidden from Swagger.
When a `SwaggerWcfTag` is added to an element, it may be configured with `HideFromSpec`.
This will prevent this tag to be displayed in the Swagger output.
When combined with `SwaggerWcfHidden`, if the tag has the value `visible` as `true` in `web.config` file, the element will be visible
## Query Parameter
To specify query parameters to a function you may use the following syntax
```csharp
[WebGet(UriTemplate = "/books?filter={filter}", BodyStyle = WebMessageBodyStyle.Bare)]
Book[] ReadBooks(string filter = null);
```
## Optional Parameters
To specify a paramter as optional for swagger-ui provide a default value for the parameter on the interface.
```csharp
public string Foo(string bar = null);
```
## Optional Properties
To mark a property as optional or required, use the `IsRequired` parameter on the `DataMember` attribute.
## TODO
* Add some options to configuration in `Web.config`
* Tests
## How to Improve It
Fork this project [abelsilva/swaggerwcf](https://github.com/abelsilva/swaggerwcf) and submit pull requests.