swaager转md

 import os                                                                                                                                                                                                                        
  import sys                                                                                                                                                                                                                       
  import json                                                                                                                                                                                                                      
  import yaml                                                                                                                                                                                                                      
                                                                                                                                                                                                                                   
  def load_swagger(file_path):                                                                                                                                                                                                     
      with open(file_path, "r", encoding="utf-8") as f:                                                                                                                                                                            
          file_ext = os.path.splitext(file_path)[1].lower()                                                                                                                                                                        
          if file_ext in [".yaml", ".yml"]:                                                                                                                                                                                        
              return yaml.safe_load(f)                                                                                                                                                                                             
          else:                                                                                                                                                                                                                    
              return json.load(f)                                                                                                                                                                                                  
                                                                                                                                                                                                                                   
  def parse_parameters(params):                                                                                                                                                                                                    
      lines = []                                                                                                                                                                                                                   
      if not params:                                                                                                                                                                                                               
          return lines                                                                                                                                                                                                             
      lines.append("| Name | In | Type | Required | Description |")                                                                                                                                                                
      lines.append("|------|----|------|----------|-------------|")                                                                                                                                                                
      for p in params:                                                                                                                                                                                                             
          name = p.get("name", "")                                                                                                                                                                                                 
          location = p.get("in", "")                                                                                                                                                                                               
          typ = p.get("schema", {}).get("type", p.get("type", ""))                                                                                                                                                                 
          required = str(p.get("required", False))                                                                                                                                                                                 
          desc = p.get("description", "").replace("\n", " ")                                                                                                                                                                       
          lines.append(f"| {name} | {location} | {typ} | {required} | {desc} |")                                                                                                                                                   
      return lines                                                                                                                                                                                                                 
                                                                                                                                                                                                                                   
  def swagger_to_markdown(swagger):                                                                                                                                                                                                
      md_lines = []                                                                                                                                                                                                                
      info = swagger.get("info", {})                                                                                                                                                                                               
      md_lines.append(f"# {info.get('title', 'API Documentation')}")                                                                                                                                                               
      md_lines.append("")                                                                                                                                                                                                          
      md_lines.append(info.get("description", ""))                                                                                                                                                                                 
      md_lines.append("")                                                                                                                                                                                                          
                                                                                                                                                                                                                                   
      paths = swagger.get("paths", {})                                                                                                                                                                                             
      for path, methods in paths.items():                                                                                                                                                                                          
          for method, details in methods.items():                                                                                                                                                                                  
              md_lines.append(f"## `{method.upper()}` {path}")                                                                                                                                                                     
              md_lines.append("")                                                                                                                                                                                                  
              md_lines.append(details.get("summary", ""))                                                                                                                                                                          
              md_lines.append("")                                                                                                                                                                                                  
                                                                                                                                                                                                                                   
              md_lines.append("### Parameters")                                                                                                                                                                                    
              md_lines.extend(parse_parameters(details.get("parameters", [])))                                                                                                                                                     
              md_lines.append("")                                                                                                                                                                                                  
                                                                                                                                                                                                                                   
              # Responses (simple display of status codes)                                                                                                                                                                         
              responses = details.get("responses", {})                                                                                                                                                                             
              md_lines.append("### Responses")                                                                                                                                                                                     
              for code, resp in responses.items():                                                                                                                                                                                 
                  desc = resp.get("description", "")                                                                                                                                                                               
                  md_lines.append(f"- **{code}**: {desc}")                                                                                                                                                                         
              md_lines.append("")                                                                                                                                                                                                  
      return "\n".join(md_lines)                                                                                                                                                                                                   
                                                                                                                                                                                                                                   
  def main():                                                                                                                                                                                                                      
      if len(sys.argv) < 2:                                                                                                                                                                                                        
          print("Usage: python swagger_to_md.py <swagger-file> [output-md-file]")                                                                                                                                                  
          sys.exit(1)                                                                                                                                                                                                              
                                                                                                                                                                                                                                   
      swagger_file = sys.argv[1]                                                                                                                                                                                                   
      output_file = sys.argv[2] if len(sys.argv) > 2 else None                                                                                                                                                                     
                                                                                                                                                                                                                                   
      swagger = load_swagger(swagger_file)                                                                                                                                                                                         
      md_content = swagger_to_markdown(swagger)                                                                                                                                                                                    
                                                                                                                                                                                                                                   
      if output_file:                                                                                                                                                                                                              
          with open(output_file, "w", encoding="utf-8") as f:                                                                                                                                                                      
              f.write(md_content)                                                                                                                                                                                                  
          print(f"Markdown documentation generated at {output_file}")                                                                                                                                                              
      else:                                                                                                                                                                                                                        
          print(md_content)                                                                                                                                                                                                        
                                                                                                                                                                                                                                   
  if __name__ == "__main__":                                                                                                                                                                                                       
      main()                  

　　

安装依赖：

 pip install pyyaml