Блог

Я пишу документацию swagger для API, и поля «описание» становятся довольно длинными, и их трудно редактировать.

 {
  "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>",
        ...
      }
    },
    ...
  },
 

Эти описания важны, потому что первое отображается сверху, когда пользователь просматривает страницу swagger; а другие описания появляются в начале каждого пути.

Меня просят добавить еще кое-что в описания.

Возможно ли иметь описание в отдельном файле, а затем импортировать / включить его?

У меня было аналогичное требование, и я решил его, используя методы расширения в c #. Также помогло сохранить метод запуска в чистоте.

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

Добавьте статический метод в статический класс, как показано ниже

 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;
    }
}