CODEWITHSUNDEEP
.net-coreswaggerasp.net-core-webapiswashbuckle.aspnetcore
Soft_API_Dev
Soft_API_Dev

Reputation: 373

Add request schema to swagger description

I am using .Net core 3.1 and working on documenting API actions in Swagger and want to document request body so that it would show all details like data types, validations etc to the end users.

Currently, I am hard coding the schema in xml comments as follows-

    /// <summary>
    /// Order Details
    /// </summary>
    /// <remarks>
    /// Parameter's description:
    ///
    ///     {
    ///        "productName": string,                           -- Required
    ///        "isUsed: true,                                   
    ///        "orderDate": "2021-02-19T08:43:10.300Z",         -- Required
    ///        "discountDate": "2021-02-19T08:43:10.300Z"
    ///     }       
    /// </remarks>
    /// <returns>Returns Order results</returns>  
    /// <response code="200">Order Placed</response>           
    [HttpPost]
    [Route("Place Order")]
    public ActionResult<OrderPlacingResult> PlaceOrder(OrderPlaceParam orderPlaceParam)
    {
         ///
    }

This gives the desired result and is feasible for small request body. However, if the request contains lots of parameters, it would not be advisable to hard code it in the description section.

Can anyone suggest a better way to document parameters such that it will give all the details that it provides in the schema.
Please note the request has no actual parameters, I want to document request body.

Upvotes: 3

Views: 8684

Answers (2)

Serge P
Serge P

Reputation: 1161

Instead of describing parameters itself in remarks section of the method/function, request/response models should be documented itself (apply summary tag). Later on it can be found in swagger documentation. Check all screenshots bellow please to see how it works in action.

P.S. I attached screenshots instead of classes on purpose as code from production, sorry.

XML tags applied to controller Example of request model Example of method in UI Schema of request model Schema of response model

Upvotes: 1

sa-es-ir
sa-es-ir

Reputation: 5102

Swagger use api summary to generate document and if you don't write those summary then you have no document. but you can avoid to write all description in code and create swagger json and tell swagger to use this file. when you add this line in startup:

public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(options =>
            {
                //set options
            });
       }
       
 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.RoutePrefix = "docs";
                c.DocumentTitle = " Api Title";
            });
         }

You can see documents in http://localhost:{port}/docs. and also you can see Swagger generated json file in this route:

http://localhost:{port}/swagger/v1/swagger.json

So, you can save this json and edit any thing in it and you can remove your summary from api or just have few line to describe your api, assume that you save file in you app root and you should add it like this in app configure:

 app.Map("/swagger/v1/savedfile.json", b =>
                    {
                        b.Run(x =>
                           File.ReadAllTextAsync(Path.Combine(AppContext.BaseDirectory,
                                   "savedfile.json"))
                               .ContinueWith(readTask => x.Response.WriteAsync(readTask.Result))
                            );
                    }).UseSwaggerUI(c =>
                    {
                        c.SwaggerEndpoint("/swagger/v1/savedfile.json", "My API V1");
                        c.RoutePrefix = "docs";
                        c.DocumentTitle = "Api Title";
                    });

Upvotes: 0

Related Questions