How to Generate Basic Swagger yaml Description for WCF Automatically on Build Time with Swagger4WCF .NET 4.0+

Introduction

It can be very boring to manually write yaml description for swagger and maintain it especially when your WCF services are very simple. There is a nuget package called Swagger4WCF that automatically generates yaml description for swagger 2.0 for each interface matching attributes used by WCF (ServiceContract/OperationContract/WebGet/WebInvoke).

How to Use Swagger4WCF

There are only a few step required to test it:

1. Create a library with WCF interface:

   /// <summary>
   /// Represent a book
   /// </summary>
   [DataContract]
   public class Book
   {
       /// <summary>
       /// Book id
       /// </summary>
       [DataMember]
       public int Id { get; set; }
   
       /// <summary>
       /// Book name
       /// </summary>
       [DataMember]
       public string Name { get; set; }
   }
   

   /// <summary>
   /// Service crud for book
   /// </summary>
   [ServiceContract]
   public interface IBookService
   {
       /// <summary>
       /// Get list of book
       /// </summary>
       /// <returns>list of book</returns>
       [OperationContract]
       [WebGet(RequestFormat = WebMessageFormat.Json,
       ResponseFormat = WebMessageFormat.Json)]
       Book[] GetBooksList();
   
       /// <summary>
       /// Get book by id
       /// </summary>
       /// <param name="id">book id</param>
       /// <returns>book</returns>
       [OperationContract]
       [WebGet(RequestFormat = WebMessageFormat.Json,
       ResponseFormat = WebMessageFormat.Json)]
       Book GetBookById(string id);
   
       /// <summary>
       /// Add book
       /// </summary>
       /// <param name="name">name of book</param>
       /// <returns>id of book</returns>
       [OperationContract]
       [WebInvoke(Method = "PUT",
       RequestFormat = WebMessageFormat.Json, ResponseFormat = WebMessageFormat.Json)]
       void AddBook(string name);
   
       /// <summary>
       /// Update book
       /// </summary>
       /// <param name="id">if of book</param>
       /// <param name="name">name of book</param>
       /// <returns>id of book</returns>
       [OperationContract]
       [WebInvoke(Method = "POST",
       RequestFormat = WebMessageFormat.Json, ResponseFormat = WebMessageFormat.Json)]
       void UpdateBook(string id, string name);
   
       /// <summary>
       /// Delete book
       /// </summary>
       /// <param name="id">id of book</param>
       /// <returns>id of book</returns>
       [OperationContract]
       [WebInvoke(Method = "DELETE",
       RequestFormat = WebMessageFormat.Json, ResponseFormat = WebMessageFormat.Json)]
       void DeleteBook(string id);
   }
   

2. Configure your project to generate documentation:

   In properties of project > build tab > XML documentation file (do not specify path of documentation, it will provide default path that Swagger4WCF looks for).

   

3. Install nuget package on project where WCF interfaces are declared:

   https://www.nuget.org/packages/Swagger4WCF

   

4. Build your project will trigger Swagger4WCF:

   

You can see yaml in output directory!

Test the Generated yaml in Swagger Editor Online

Copy content of the generated yaml and Rendez vous to swagger online editor:

http://editor.swagger.io/#/

Clean swagger editor to get started:

Then paste the content of your generated yaml:

How It Works in the Background

Swagger4WCF uses NuPack postbuild pattern to trigger at build time.

https://www.codeproject.com/Tips/1190360/How-to-setup-a-managed-postbuild-without-scripting

At build time, it will detect assemblies present in output directory, open them with mono.cecil (to reflect assemblies) to generate expected yaml description for swagger 2.0.

Swagger4WCF detects WebGet/WebInvoke to provide Verb/Method in serialization style in yaml.

Conclusion

Swagger4WCF may help you to save time when developing web application. It is easy to test, use or remove. It can be a nice starter for a newbie in swagger technology because it is only required to install a nuget package. Unfortunately, it is not mature enough for advanced WCF configuration, but I'm sure it can be improved.