in swagger openapi file, can I have "description" in a separate file?

Question

I'm writing swagger documentation for an API, and the "description" fields are getting pretty long, and hard to edit.

{
  "openapi": "3.0.0",
  "info": {
    "version": "2.0.0",
    "title": "My API",
    "description": "<h2>A very very long description</h2><p>which includes html tags</p>",
    ...
  },
  "paths": {
    "/somepath": {
      "get": {
        "description": "<h3>Another</h3><p>extremely long description... </p><p>that wraps over 50 lines</p>",
        ...
      }
    },
    ...
  },

These descriptions are important, because the first one shows on top when a user views the swagger page; and other descriptions appear at the beginning of each path.

I'm being asked to add some more stuff into descriptions.

Would it be possible to have description in a separate file, and then import/include it?

Answer 1

I had a similar requirement and solved it using extension methods in c#. Also helped in keeping the startup method clean.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "Trimble Connect Bim API", 
        Version = "v1",
        Description = ApiSpecExtension.GetDescription()
    });
    c.EnableAnnotations();
}

Add a static method in a static class as below

public static class ApiSpecExtension
{
    public static string GetDescription()
    {
        string description = "Your long description" +
                   "# Heading 1" +
                   "## Heading 2" +
                   "### Heading 3" +
                   "| HTTP Status |  Error Code | Retry  |\n" +  
                   "| ----------- | ----------- | ------ |\n" + 
                   "|    400      | Bad request |   No   |+n";                                    
       return description;
    }
}