stojy / swaggerwcf

Swagger for WCF

SwaggerWcf

Generates Swagger (2.0) for WCF services and also provides swagger-ui.

With an API described in Swagger you can use multiple Swagger tools like client generators, see swagger-codegen for more details.

This project has started as a fork from 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

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

<serviceHostingEnvironment aspNetCompatibilityEnabled="true" multipleSiteBindingsEnabled="true"/>

Self Hosted

Add an endpoint to your App.config file.

<services>
  <service name="SwaggerWcf.SwaggerWcfEndpoint">
    <endpoint address="http://localhost/docs" binding="webHttpBinding" contract="SwaggerWcf.ISwaggerWcfEndpoint" />
  </service>
</services>

Create a WebServiceHost

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.

<system.serviceModel>
  <behaviors>
    <endpointBehaviors>
      <behavior>
        <webHttp automaticFormatSelectionEnabled="true" />
      </behavior>
    </endpointBehaviors>
    <!-- [.......] -->
  </behaviors>
</system.serviceModel>
  

Step 4: Configure WCF services general information

Configure via config file

Add the following to your config file and change the values accordingly

<configSections>
  <section name="swaggerwcf" type="SwaggerWcf.Configuration.SwaggerWcfSection, SwaggerWcf" />
</configSections>

<swaggerwcf>
  <tags>
    <tag name="LowPerformance" visible="false" />
  </tags>
  <settings>
    <setting name="InfoDescription" value="Sample Service to test SwaggerWCF" />
    <setting name="InfoVersion" value="0.0.1" />
    <setting name="InfoTermsOfService" value="Terms of Service" />
    <setting name="InfoTitle" value="SampleService" />
    <setting name="InfoContactName" value="Abel Silva" />
    <setting name="InfoContactUrl" value="http://github.com/abelsilva" />
    <setting name="InfoContactEmail" value="[e-mail]" />
    <setting name="InfoLicenseUrl" value="https://github.com/abelsilva/SwaggerWCF/blob/master/LICENSE" />
    <setting name="InfoLicenseName" value="Apache License" />
  </settings>
</swaggerwcf>

Notes:

• make sure the configSections block is the first child of configuration
• tags will be described further down

Configure via code

SwaggerWcfEndpoint.Configure(new SwaggerWcf.Models.Info
{
    Description = "Sample Service to test SwaggerWCF",
    Version = "0.0.1"
    // etc
});

Step 5: Decorate WCF services interfaces

For each method, configure the WebInvoke or WebGet attribute, and add a SwaggerWcfPath attribute.

[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.

[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

[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
SwaggerWcfPath	Method	Configure a method in Swagger	Summary, Description, OperationId, ExternalDocsDescription, ExternalDocsUrl, Deprecated
SwaggerWcfParameter	Parameter	Configure method parameters	Required, Description
SwaggerWcfResponse	Method	Configure method return value	Code, Description, EmptyResponseOverride, Headers
SwaggerWcfDefinition	Class	Configure a data type	ExternalDocsDescription, ExternalDocsUrl

Tags

Tags are used to create categories in Swagger UI.

In SwaggerWcf they can also be used to hide 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.

Optional Parameters

To specify a paramter as optional for swagger-ui provide a default value for the parameter on the interface.

public string Foo(string bar = null);

TODO

• Add some options to configuration in Web.config
• Tests

How to Improve It

Fork this project abelsilva/swaggerwcf and submit pull requests.