transducer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec4069db4028d341c58598e45bdefdd0749e92092e4362b491845f350dc7e3df
+  data.tar.gz: 6cc2eeca6343cdcf575f76f1405bbe10066be7d6b1934193ed3b8b10215b1ff8
+SHA512:
+  metadata.gz: c2ecf6366f6121751bf0bf2a160264b087b6bb592f6f92a802f7b46acf0040fbd52f9068de01f97197ed566f1dc954c38d8fe718db51bd71f46d5d6300e5a17a
+  data.tar.gz: 4d1480b86c0134a6155c29a625ffccc49fcb833c64ab96cddf42f13d41bdce553a082c5cf454744351c1b7cec577e5ed86c9ea9e42611c1950d3bc0ee9ac7a75

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2025-12-11
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,214 @@
+# Transducer
+
+Generate Markdown documentation from OpenAPI specifications.
+
+Transducer is a Ruby gem that reads OpenAPI YAML specifications (versions 3.0.x and 3.1.x) and generates well-formatted, readable Markdown documentation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'transducer'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install transducer
+```
+
+## Usage
+
+### Command Line
+
+Generate Markdown documentation from an OpenAPI specification:
+
+```bash
+$ transducer generate input.yaml -o output.md
+```
+
+Options:
+- `-o, --output`: Output file path (default: `docs/openapi.md`)
+- `-t, --template`: Custom ERB template file path
+
+#### Using Custom Templates
+
+You can customize the output format using ERB templates:
+
+```bash
+$ transducer generate input.yaml --template=custom.md.erb --output=api.md
+```
+
+Template variables available:
+- `data`: Parsed OpenAPI specification hash
+- `formatter`: Formatter instance for formatting endpoints, parameters, schemas, etc.
+
+Example custom template:
+
+```erb
+# <%= data['info']['title'] %>
+
+<% data['paths']&.each do |path, methods| %>
+  <% methods.each do |method, details| %>
+### <%= method.upcase %> <%= path %>
+<%= formatter.format_endpoint(path, method, details) %>
+  <% end %>
+<% end %>
+```
+
+Display version information:
+
+```bash
+$ transducer version
+```
+
+Display help:
+
+```bash
+$ transducer help
+$ transducer help generate
+```
+
+### Programmatic Usage
+
+You can also use Transducer programmatically in your Ruby code:
+
+```ruby
+require 'transducer'
+
+# Parse OpenAPI specification
+parser = Transducer::Parser.new('path/to/openapi.yaml')
+data = parser.parse
+
+# Generate Markdown with default template
+generator = Transducer::Generator.new(data)
+markdown = generator.generate
+
+# Or use a custom template
+generator = Transducer::Generator.new(data, template_path: 'custom.md.erb')
+markdown = generator.generate
+
+# Write to file
+generator.to_file('output.md')
+```
+
+## Output Format
+
+The generated Markdown documentation includes:
+
+- API Title and Description: From the `info` section
+- Version and Base URL: API version and server URL
+- Table of Contents: Automatically generated with links to all sections
+- Endpoints: All API endpoints with:
+  - HTTP method and path
+  - Description
+  - Parameters (path, query, header)
+  - Request body schema and examples
+  - Response codes with schemas and examples
+- Schemas: Component schemas with:
+  - Type information
+  - Property descriptions
+  - Required fields
+  - Examples
+
+### Example Output
+
+```markdown
+# Simple API
+
+A simple API for testing
+
+| | |
+|---|---|
+| Version | 1.0.0 |
+| Base URL | https://api.example.com/v1 |
+
+## Table of Contents
+
+- [Endpoints](#endpoints)
+  - [GET /users](#get-users)
+  - [POST /users](#post-users)
+- [Schemas](#schemas)
+  - [User](#user)
+
+## Endpoints
+
+### GET /users
+
+Returns a list of all users
+
+**Parameters**:
+
+| Name | Location | Type | Required | Description |
+|------|----------|------|----------|-------------|
+| limit | query | integer | No | Maximum number of users to return |
+
+**Responses**:
+
+#### 200 OK
+
+Successful response
+...
+```
+
+## Supported OpenAPI Versions
+
+- OpenAPI 3.0.x
+- OpenAPI 3.1.x
+
+OpenAPI 2.0 (Swagger) is not currently supported.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+Run tests:
+
+```bash
+$ bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+$ bundle exec rubocop
+```
+
+Run all checks (tests + RuboCop):
+
+```bash
+$ bundle exec rake
+```
+
+To install this gem onto your local machine:
+
+```bash
+$ bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version number in `lib/transducer/version.rb`
+2. Update `CHANGELOG.md`
+3. Run `bundle exec rake release`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/transducer.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/transducer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/transducer'
+
+Transducer::CLI.start(ARGV)

data/lib/transducer/cli.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Transducer
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'generate INPUT', 'Generate Markdown documentation from OpenAPI specification'
+    method_option :output, aliases: '-o', type: :string, default: 'docs/openapi.md',
+                           desc: 'Output file path for the generated Markdown'
+    method_option :template, aliases: '-t', type: :string,
+                             desc: 'Custom ERB template file path'
+    def generate(input_file)
+      unless File.exist?(input_file)
+        error "Input file not found: #{input_file}"
+        exit 1
+      end
+
+      output_file = options[:output]
+      template_path = options[:template]
+
+      parser = Parser.new(input_file)
+      data = parser.parse
+
+      generator = Generator.new(data, template_path: template_path)
+      generator.to_file(output_file)
+
+      success "Documentation generated successfully: #{output_file}"
+    rescue FileError => e
+      error "File error: #{e.message}"
+      exit 1
+    rescue ParseError => e
+      error "Parse error: #{e.message}"
+      exit 2
+    rescue ValidationError => e
+      error "Validation error: #{e.message}"
+      exit 3
+    rescue StandardError => e
+      error "Unexpected error: #{e.message}"
+      exit 4
+    end
+
+    desc 'version', 'Display version information'
+    def version
+      puts "Transducer version #{Transducer::VERSION}"
+    end
+
+    private
+
+    def success(message)
+      puts "✓ #{message}"
+    end
+
+    def error(message)
+      warn "✗ #{message}"
+    end
+  end
+end

data/lib/transducer/formatter.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Transducer
+  class Formatter
+    def format_endpoint(path, method, details)
+      output = []
+      output << "### #{method.upcase} #{path}"
+      output << ''
+      output << details['description'] if details['description']
+      output << ''
+      output << format_parameters(details['parameters']) if details['parameters']
+      output << format_request_body(details['requestBody']) if details['requestBody']
+      output << format_responses(details['responses']) if details['responses']
+      output.join("\n")
+    end
+
+    def format_parameters(parameters)
+      return '' if parameters.nil? || parameters.empty?
+
+      output = []
+      output << '**Parameters**:'
+      output << ''
+      output << '| Name | Location | Type | Required | Description |'
+      output << '|------|----------|------|----------|-------------|'
+
+      parameters.each do |param|
+        name = param['name'] || 'N/A'
+        location = param['in'] || 'N/A'
+        type = extract_type(param['schema'])
+        required = param['required'] ? 'Yes' : 'No'
+        description = param['description'] || ''
+        output << "| #{name} | #{location} | #{type} | #{required} | #{description} |"
+      end
+
+      output << ''
+      output.join("\n")
+    end
+
+    def format_request_body(request_body)
+      return '' unless request_body
+
+      output = []
+      output << '**Request Body**:'
+      output << ''
+
+      if request_body['description']
+        output << request_body['description']
+        output << ''
+      end
+
+      request_body['content']&.each do |content_type, details|
+        output << "**Content-Type**: `#{content_type}`"
+        output << ''
+        output << format_schema(details['schema']) if details['schema']
+        next unless details['example']
+
+        output << '**Example**:'
+        output << ''
+        output << '```json'
+        output << JSON.pretty_generate(details['example'])
+        output << '```'
+        output << ''
+      end
+
+      output.join("\n")
+    end
+
+    def format_responses(responses)
+      return '' unless responses
+
+      output = []
+      output << '**Responses**:'
+      output << ''
+
+      responses.each do |status_code, response|
+        output << "#### #{status_code} #{status_name(status_code)}"
+        output << ''
+        output << response['description'] if response['description']
+        output << ''
+
+        next unless response['content']
+
+        response['content'].each do |content_type, details|
+          output << "**Content-Type**: `#{content_type}`"
+          output << ''
+          if details['schema']
+            output << '**Schema**:'
+            output << ''
+            output << '```json'
+            output << JSON.pretty_generate(details['schema'])
+            output << '```'
+            output << ''
+          end
+          next unless details['example']
+
+          output << '**Example**:'
+          output << ''
+          output << '```json'
+          output << JSON.pretty_generate(details['example'])
+          output << '```'
+          output << ''
+        end
+      end
+
+      output.join("\n")
+    end
+
+    def format_schema(schema)
+      return '' unless schema
+
+      output = []
+
+      if schema['$ref']
+        ref_name = schema['$ref'].split('/').last
+        output << "**Schema**: `#{ref_name}`"
+        output << ''
+        return output.join("\n")
+      end
+
+      output << "**Type**: #{schema['type']}" if schema['type']
+      output << ''
+
+      if schema['properties']
+        output << '**Properties**:'
+        output << ''
+        output << '| Name | Type | Required | Description |'
+        output << '|------|------|----------|-------------|'
+
+        required_fields = schema['required'] || []
+        schema['properties'].each do |prop_name, prop_details|
+          type = extract_type(prop_details)
+          is_required = required_fields.include?(prop_name) ? 'Yes' : 'No'
+          description = prop_details['description'] || ''
+          output << "| #{prop_name} | #{type} | #{is_required} | #{description} |"
+        end
+        output << ''
+      end
+
+      output.join("\n")
+    end
+
+    private
+
+    def extract_type(schema)
+      return 'N/A' unless schema
+
+      if schema['$ref']
+        schema['$ref'].split('/').last
+      elsif schema['type']
+        type = schema['type']
+        if type == 'array' && schema['items']
+          item_type = extract_type(schema['items'])
+          "array[#{item_type}]"
+        else
+          type
+        end
+      else
+        'object'
+      end
+    end
+
+    def status_name(code)
+      names = {
+        '200' => 'OK',
+        '201' => 'Created',
+        '204' => 'No Content',
+        '400' => 'Bad Request',
+        '401' => 'Unauthorized',
+        '403' => 'Forbidden',
+        '404' => 'Not Found',
+        '500' => 'Internal Server Error'
+      }
+      names[code.to_s] || ''
+    end
+  end
+end

data/lib/transducer/generator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'erb'
+
+module Transducer
+  class Generator
+    attr_reader :data, :formatter, :template_path
+
+    def initialize(parsed_data, template_path: nil)
+      @data = parsed_data
+      @formatter = Formatter.new
+      @template_path = template_path
+    end
+
+    def generate
+      if @template_path
+        render_template
+      else
+        generate_default
+      end
+    end
+
+    def to_file(output_path)
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(output_path))
+
+      File.write(output_path, generate)
+    rescue Errno::EACCES
+      raise FileError, "Permission denied: #{output_path}"
+    rescue StandardError => e
+      raise FileError, "Failed to write file: #{e.message}"
+    end
+
+    private
+
+    def render_template
+      raise FileError, "Template file not found: #{@template_path}" unless File.exist?(@template_path)
+
+      template_content = File.read(@template_path)
+      erb = ERB.new(template_content, trim_mode: '-')
+      erb.result(binding)
+    rescue Errno::EACCES
+      raise FileError, "Permission denied reading template: #{@template_path}"
+    rescue StandardError => e
+      raise FileError, "Failed to render template: #{e.message}"
+    end
+
+    def generate_default
+      output = []
+      output << generate_header
+      output << generate_table_of_contents
+      output << generate_endpoints
+      output << generate_schemas
+      output.compact.join("\n\n")
+    end
+
+    def generate_header
+      info = @data['info']
+      output = []
+      output << "# #{info['title']}"
+      output << ''
+      output << info['description'] if info['description']
+      output << ''
+      output << '| | |'
+      output << '|---|---|'
+      output << "| Version | #{info['version']} |"
+
+      output << "| Base URL | #{@data['servers'][0]['url']} |" if @data['servers'] && !@data['servers'].empty?
+
+      output.join("\n")
+    end
+
+    def generate_table_of_contents
+      output = []
+      output << '## Table of Contents'
+      output << ''
+      output << '- [Endpoints](#endpoints)'
+
+      @data['paths']&.each do |path, methods|
+        methods.each_key do |method|
+          next if method.start_with?('$')
+
+          anchor = "#{method}-#{path}".downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-')
+          output << "  - [#{method.upcase} #{path}](##{anchor})"
+        end
+      end
+
+      if @data['components'] && @data['components']['schemas']
+        output << '- [Schemas](#schemas)'
+        @data['components']['schemas'].each_key do |schema_name|
+          anchor = schema_name.downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-')
+          output << "  - [#{schema_name}](##{anchor})"
+        end
+      end
+
+      output.join("\n")
+    end
+
+    def generate_endpoints
+      return nil unless @data['paths']
+
+      output = []
+      output << '## Endpoints'
+      output << ''
+
+      @data['paths'].each do |path, methods|
+        methods.each do |method, details|
+          next if method.start_with?('$')
+
+          output << @formatter.format_endpoint(path, method, details)
+          output << ''
+        end
+      end
+
+      output.join("\n")
+    end
+
+    def generate_schemas
+      return nil unless @data['components'] && @data['components']['schemas']
+
+      output = []
+      output << '## Schemas'
+      output << ''
+
+      @data['components']['schemas'].each do |schema_name, schema|
+        output << "### #{schema_name}"
+        output << ''
+        output << schema['description'] if schema['description']
+        output << ''
+        output << @formatter.format_schema(schema)
+        output << ''
+
+        next unless schema['example']
+
+        output << '**Example**:'
+        output << ''
+        output << '```json'
+        output << JSON.pretty_generate(schema['example'])
+        output << '```'
+        output << ''
+      end
+
+      output.join("\n")
+    end
+  end
+end

data/lib/transducer/parser.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module Transducer
+  class Parser
+    attr_reader :file_path, :data, :errors
+
+    def initialize(file_path)
+      @file_path = file_path
+      @data = nil
+      @errors = []
+    end
+
+    def parse
+      raise FileError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+      begin
+        @data = Psych.safe_load_file(file_path, permitted_classes: [Symbol, Date, Time])
+      rescue Psych::SyntaxError => e
+        raise ParseError, "YAML syntax error at line #{e.line}: #{e.message}"
+      end
+
+      validate_openapi_spec
+      @data
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    private
+
+    def validate_openapi_spec
+      @errors = []
+
+      unless @data.is_a?(Hash)
+        @errors << 'OpenAPI specification must be a hash'
+        raise ValidationError, @errors.join(', ')
+      end
+
+      validate_openapi_version
+      validate_info
+      validate_paths
+
+      raise ValidationError, @errors.join(', ') unless valid?
+    end
+
+    def validate_openapi_version
+      unless @data['openapi']
+        @errors << 'Missing required field: openapi'
+        return
+      end
+
+      version = @data['openapi'].to_s
+      return if version.start_with?('3.0') || version.start_with?('3.1')
+
+      @errors << "Unsupported OpenAPI version: #{version}. Only 3.0.x and 3.1.x are supported."
+    end
+
+    def validate_info
+      unless @data['info']
+        @errors << 'Missing required field: info'
+        return
+      end
+
+      info = @data['info']
+      @errors << 'Missing required field: info.title' unless info['title']
+      @errors << 'Missing required field: info.version' unless info['version']
+    end
+
+    def validate_paths
+      @errors << 'Missing required field: paths' unless @data['paths']
+    end
+  end
+end

data/lib/transducer/templates/default.md.erb

@@ -0,0 +1,61 @@
+# <%= data['info']['title'] %>
+
+<% if data['info']['description'] %>
+<%= data['info']['description'] %>
+
+<% end %>
+**Version**: <%= data['info']['version'] %>
+<% if data['servers'] && !data['servers'].empty? %>
+**Base URL**: <%= data['servers'][0]['url'] %>
+<% end %>
+
+## Table of Contents
+
+- [Endpoints](#endpoints)
+<% data['paths']&.each do |path, methods| %>
+  <% methods.each_key do |method| %>
+    <% next if method.start_with?('$') %>
+    <% anchor = "#{method}-#{path}".downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-') %>
+  - [<%= method.upcase %> <%= path %>](#<%= anchor %>)
+  <% end %>
+<% end %>
+<% if data['components'] && data['components']['schemas'] %>
+- [Schemas](#schemas)
+  <% data['components']['schemas'].each_key do |schema_name| %>
+    <% anchor = schema_name.downcase.gsub(/[^a-z0-9\s-]/, '').gsub(/\s+/, '-') %>
+  - [<%= schema_name %>](#<%= anchor %>)
+  <% end %>
+<% end %>
+
+## Endpoints
+
+<% data['paths']&.each do |path, methods| %>
+  <% methods.each do |method, details| %>
+    <% next if method.start_with?('$') %>
+<%= formatter.format_endpoint(path, method, details) %>
+
+  <% end %>
+<% end %>
+<% if data['components'] && data['components']['schemas'] %>
+
+## Schemas
+
+  <% data['components']['schemas'].each do |schema_name, schema| %>
+### <%= schema_name %>
+
+    <% if schema['description'] %>
+<%= schema['description'] %>
+
+    <% end %>
+<%= formatter.format_schema(schema) %>
+
+    <% if schema['example'] %>
+**Example**:
+
+```json
+<%= JSON.pretty_generate(schema['example']) %>
+```
+
+    <% end %>
+  <% end %>
+<% end %>

data/lib/transducer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Transducer
+  VERSION = '0.1.0'
+end

data/lib/transducer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'transducer/version'
+require_relative 'transducer/parser'
+require_relative 'transducer/formatter'
+require_relative 'transducer/generator'
+require_relative 'transducer/cli'
+
+module Transducer
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class ValidationError < Error; end
+  class FileError < Error; end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: transducer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A Ruby gem that reads OpenAPI YAML specifications and generates well-formatted
+  Markdown documentation
+email:
+- t.yudai92@gmail.com
+executables:
+- transducer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/transducer
+- lib/transducer.rb
+- lib/transducer/cli.rb
+- lib/transducer/formatter.rb
+- lib/transducer/generator.rb
+- lib/transducer/parser.rb
+- lib/transducer/templates/default.md.erb
+- lib/transducer/version.rb
+homepage: https://github.com/ydah/transducer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/transducer
+  source_code_uri: https://github.com/ydah/transducer
+  changelog_uri: https://github.com/ydah/transducer/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate Markdown documentation from OpenAPI specifications
+test_files: []