Post
Ask Question

Swagger (3), Customized for REST Web API

Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI specification. Swagger UI is an alternative to Postman.

We make this article in the group of Swagger:related:

Introduction

With REST Web API, we use verb to define the behavior,

while the URI (noun) to identify a resource. However, sometimes, the verb and noun combinations are sill not enough to describe the features of the Web API. Therefore, more explanations might need for REST client. This article will discuss how to add C# comments into Swagger.

This is the contents of the article:

  • Introduction
  • A - XML Documentation Comments (C# Programming Guide)
  • B - 1: Write Special Comments into a XML file by .NET
  • B - 2: Write Special Comments into Swagger notes by .NET
  • C - 1: Write Special Comments into a XML file by .NET Core
  • C - 2: Write Special Comments into Swagger notes .NET Core

A - XML Documentation Comments (C# Programming Guide)

Special form of C# Comments

Comments having a certain (special) form can be used to direct a tool to produce XML from those comments and the source code elements that they precede. Such comments are Single-Line_Comments (§6.3.3) that start with three slashes (///), or Delimited_Comments (§6.3.3) that start with a slash and two asterisks (/**). 

Single_Line_Doc_Comment
    : '///' Input_Character*
    ;
   
Delimited_Doc_Comment
    : '/**' Delimited_Comment_Section* ASTERISK+ '/'
    ;

The Location of Special Comments

They must immediately precede a user-defined type or a member that they annotate. Attribute sections (§21.3) are considered part of declarations, so documentation comments must precede attributes applied to a type or member. For example:

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

Write Special Comments into a XML file by Command:

When you compile with /doc the compiler will search for all XML tags in the source code and create an XML documentation file. 

You may see a sample page from How to: Use the XML Documentation Features (C# Programming Guide) | Microsoft Docs.

In code,

In output XML file,

<member name="T:SomeClass">
    <summary> Class level summary documentation goes here.</summary>
        <remarks> Longer comments can be associated with a type or member through the remarks tag</remarks>
    </member>
<member name="F:SomeClass.m_Name">

B - 1: Write Special Comments into a XML file by .NET:

Write Special Comments into Web API:

Source Code:

Make the XML file as an output: --- equivalent to using /doc option comipling in command line:

Right Click the Project ==> Properties ==> Build ==> output ==> Check XML document file with the path

The output XML file:  --- In the location at bin\WebBlogApi.xml

B - 2: Write Special Comments into Swagger notes by .NET

This swagger original form, even we can use REST verb and Web API name (noun) to distinguish the entity and anctionality, sometime there are still not enough. Now, the C# Special Comments will play a role.

Configure Swagger

After we have the XML file with C# Special Comments in, we can exmport the info into Swagger, by configuring Swagger:

Swagger with Special Comments Notes:

C - 1: Write Special Comments into a XML file by .NET Core

Make the XML file as an output: --- equivalent to using /doc option comipling in command line:

Right Click the Project ==> Properties ==> Build ==> output ==> Check XML document file with the path, this is Visual Studio 2022:

The output XML file:  --- by default goto the location at bin\Debug\net5.0\WebBlogApi.xml

C - 2: Write Special Comments into Swagger notes .NET Core

This is for .Net Core, original output

Configure Swagger

Swagger with Special Comments Notes

Reference


Similar Articles