发表新帖
发表新帖

Swagger UI Web Api documentation Present enums as strings?

后端 未结
关注
20 2008
半阙折子戏
半阙折子戏 2020-11-27 11:31

Is there a way to display all enums as their string value in swagger instead of their int value?

I want to be able to submit POST actions and put enums according to

20条回答
  • 眼角桃花
    眼角桃花 (楼主)
    2020-11-27 11:45

    So I think I have a similar problem. I'm looking for swagger to generate enums along with the int -> string mapping. The API must accept the int. The swagger-ui matters less, what I really want is code generation with a "real" enum on the other side (android apps using retrofit in this case).

    So from my research this ultimately seems to be a limit of the OpenAPI specification which Swagger uses. It's not possible to specify names and numbers for enums.

    The best issue I've found to follow is https://github.com/OAI/OpenAPI-Specification/issues/681 which looks like a "maybe soon" but then Swagger would have to be updated, and in my case Swashbuckle as well.

    For now my workaround has been to implement a document filter that looks for enums and populates the relevant description with the contents of the enum.

            GlobalConfiguration.Configuration
            .EnableSwagger(c =>
                {
                    c.DocumentFilter();

                    //disable this
                    //c.DescribeAllEnumsAsStrings()

    SwaggerAddEnumDescriptions.cs:

    using System;
using System.Web.Http.Description;
using Swashbuckle.Swagger;
using System.Collections.Generic;

public class SwaggerAddEnumDescriptions : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        // add enum descriptions to result models
        foreach (KeyValuePair schemaDictionaryItem in swaggerDoc.definitions)
        {
            Schema schema = schemaDictionaryItem.Value;
            foreach (KeyValuePair propertyDictionaryItem in schema.properties)
            {
                Schema property = propertyDictionaryItem.Value;
                IList propertyEnums = property.@enum;
                if (propertyEnums != null && propertyEnums.Count > 0)
                {
                    property.description += DescribeEnum(propertyEnums);
                }
            }
        }

        // add enum descriptions to input parameters
        if (swaggerDoc.paths.Count > 0)
        {
            foreach (PathItem pathItem in swaggerDoc.paths.Values)
            {
                DescribeEnumParameters(pathItem.parameters);

                // head, patch, options, delete left out
                List possibleParameterisedOperations = new List { pathItem.get, pathItem.post, pathItem.put };
                possibleParameterisedOperations.FindAll(x => x != null).ForEach(x => DescribeEnumParameters(x.parameters));
            }
        }
    }

    private void DescribeEnumParameters(IList parameters)
    {
        if (parameters != null)
        {
            foreach (Parameter param in parameters)
            {
                IList paramEnums = param.@enum;
                if (paramEnums != null && paramEnums.Count > 0)
                {
                    param.description += DescribeEnum(paramEnums);
                }
            }
        }
    }

    private string DescribeEnum(IList enums)
    {
        List enumDescriptions = new List();
        foreach (object enumOption in enums)
        {
            enumDescriptions.Add(string.Format("{0} = {1}", (int)enumOption, Enum.GetName(enumOption.GetType(), enumOption)));
        }
        return string.Join(", ", enumDescriptions.ToArray());
    }

}



    This results in something like the following on your swagger-ui so at least you can "see what you're doing":

    
    
    
             
    
                                                        
    
            
            
    
              
                
                0
              
                   
                
               讨论(0)
              
                                                  
              
              
    
                          
             
       
          
              
    
                                       
    

    

                
    
                         
          
                              			
        
        
        
    
          
    
            
            
    
              
              
    
            
    


                                 
              
    
            
    
                          
    

        
         
    
                
                
    
                  
                
    
                
    
                   看不清?
                
    
              
    
                                  
    
                    
   
                 
             
              
    提交回复
    
            
    
          
    
        
    
      
       
      
    
    
    
          
 
     
 
    
        
    热议问题