CODEWITHSUNDEEP
swagger.net-5swashbuckleswashbuckle.aspnetcore
David Mason
David Mason

Reputation: 1439

Swashbuckle should use my controller action names as default summary

I am using Swashbuckle to generate my API definitions in a .NET 5 project.
To add a summary and remarks to my documentation, I am currently putting a comment on some of my actions like this:

    /// <summary>
    /// CreateSite
    /// </summary>
    /// <remarks>
    /// Options:
    /// * Enterprise = 0,
    /// * Site = 1
    /// * Order = 2
    /// * Line = 3
    /// * Product = 4
    /// 
    /// </remarks>
    [HttpPost]
    [Route("sites")]
    public async Task<IActionResult> CreateSiteAsync([FromBody] SiteCreateRequest createRequest)
    { // My controller stuff }

This generates a nice documentation and is very helpful.
Howevery, my "summary" field has always the same value like my controller action name - I already put efford in a very good naming of the actions:
You can see above that the summary contains "CreateSite" and my controller name is "CreateSiteAsync".
Is there a way to automatize this?
So could I set some option in the service to use the controller name as a "default" summary option used in the json file?

Then I can just avoid this cumbersome comments in the all simple requests without the need of any docu.

Upvotes: 0

Views: 324

Answers (1)

EspressoBeans
EspressoBeans

Reputation: 2015

I also use Swashbuckle and to properly document my APIs I use Swagger tags. Attached is an example of my actual use. For your specific controller name tag, in my example it would be [SwaggerOperation("In-Transit Shipments")]

        /// <summary>
        /// In-transit shipments 
        /// </summary>
        /// <remarks>
        /// Get in-transit shipments for a client
        /// </remarks>
        /// <returns></returns>
        [SwaggerTag("GroundTransportation")]
        [SwaggerOperation("In-Transit Shipments")]
        [SwaggerResponse(200, typeof(List<LoadSummaryDto>), Description = "OK")]
        [SwaggerResponse(400, typeof(ErrorMessageDto), Description = "Bad Request")]
        [SwaggerResponse(404, typeof(ErrorMessageDto), Description = "Not Found")]
        [SwaggerOperationProcessor(typeof(ReDocCodeSampleAppender), "Curl,CSharp,Java")]
        [HttpGet("ShipmentInformation/In-Transit")]
        [TraceAction(message: "Controller: Retrieving in-transit shipments for client", level: LogLevel.Information, externalErrorMessage: "In-transit shipments could not be found")]
        public async Task<IActionResult> GetClientInTransitShipments(uint? page = GroundTransportationConstants.DefaultPage, uint? pageSize = GroundTransportationConstants.DefaultPageSize)
        {
           // ... a bunch of api code :-)
        }

Upvotes: 0

Related Questions