Extend OpenAPI support

[kostas-jonauskas]

/// <summary>
/// Gets the complete list of available converters.
/// </summary>
/// <returns>
/// Yields the list of <see cref="ConverterDto"/> items
/// </returns>
List<ConverterDto> GetAllConverters();

/// <summary>
/// Gets a single converter definition by source and destination formats.
/// </summary>
/// <param name="sourceFormat">The source format identifier (e.g., "pdf").</param>
/// <param name="destinationFormat">The destination format identifier (e.g., "docx").</param>
/// <returns>
/// The matching <see cref="ConverterDto"/> if found; otherwise, <c>null</c>.
/// </returns>
ConverterDto GetConverter(string sourceFormat, string destinationFormat);

/// <summary>
/// Gets converters filtered by the specified tags.
/// </summary>
/// <param name="tags">
/// A list of tag names to filter by. When provided, only converters that contain all of the
/// specified tags are returned. If <c>null</c> or empty, all converters are returned.
/// </param>
/// <returns>A list of <see cref="ConverterDto"/> that match the tag criteria.</returns>
List<ConverterDto> GetConvertersByTags(List<string> tags = null);

/// <summary>
/// Searches for converters by the provided search terms.
/// </summary>
/// <param name="terms">Array of terms to search for (e.g., fragments of formats, titles, or descriptions).</param>
/// <returns>A list of <see cref="ConverterDto"/> that meet the search criteria.</returns>
List<ConverterDto> SearchConverters(string[] terms);

/// <summary>
/// Gets the list of available tags.
/// </summary>
/// <returns>
/// Yields the list of <see cref="TagDto"/> items.
/// </returns>
List<TagDto> GetTags();

/// <summary>
/// Reloads converter and tag information from the underlying CARA service and updates the cache.
/// </summary>
Task Reload();

[kostas-jonauskas]

Models

public class ConverterDto
{
    public string Summary { get; set; }
    public string Description { get; set; }
    public string Overview { get; set; }
    public string MetaTitle { get; set; }
    public string MetaDescription { get; set; }
    public List<string> Tags { get; set; }
    public string SourceFormat { get; set; }
    public string DestinationFormat { get; set; }
    public List<string> SourceExtensions { get; set; }
    public List<string> DestinationExtensions { get; set; }
    public IEnumerable<ConverterParameterGroupDto> ConverterParameterGroups { get; set; }
}

public class ConverterParameterGroupDto
{
    public string Name { get; set; }
    public IEnumerable<ConverterParameterDto> ConverterParameters { get; set; }
}

public class ConverterParameterDto
{
    public string Name { get; set; }
    public string Label { get; set; }
    public string Description { get; set; }
    public string GroupName { get; set; }
    public string Type { get; set; }
    public string Representation { get; set; }
    public object Default { get; set; }
    public Dictionary<string, string> Values { get; set; }
    public ConverterParameterRangeDto Range { get; set; }
    public bool Required { get; set; }
    public bool Featured { get; set; }
    public bool Array { get; set; }
    public string[] AllowedExtensions { get; set; }
}

public class ConverterParameterRangeDto
{
    public string From { get; set; }
    public string To { get; set; }
}

public class TagDto
{
    public string Name { get; set; }
    public string Summary { get; set; }
    public string Description { get; set; }
    public string PageTitle { get; set; }
    public string FriendlyName { get; set; }
    public string MetaTitle { get; set; }
    public string MetaDescription { get; set; }
}

[kostas-jonauskas]

Attaching the OpenAPI specification example:

openapi.json