# frozen_string_literal: true
require_relative 'open_api/info_object'
require_relative 'open_api/server_object'
require_relative 'open_api/paths_object'
require_relative 'open_api/tag_object'
module Praxis
module Docs
class OpenApiGenerator
require 'active_support/core_ext/enumerable' # For index_by
include Singleton
API_DOCS_DIRNAME = 'docs/openapi'
EXCLUDED_TYPES_FROM_OUTPUT = Set.new([
Attributor::Boolean,
Attributor::CSV,
Attributor::DateTime,
Attributor::Date,
Attributor::Float,
Attributor::Hash,
Attributor::Ids,
Attributor::Integer,
Attributor::Object,
Attributor::String,
Attributor::Symbol,
Attributor::URI
]).freeze
attr_reader :resources_by_version, :infos_by_version, :doc_root_dir
# substitutes ":params_like_so" for {params_like_so}
def self.templatize_url(string)
Mustermann.new(string).to_templates.first
end
def save!
raise 'You need to configure the root directory before saving (configure_root(
))' unless @root
initialize_directories
# Restrict the versions listed in the index file to the ones for which we have at least 1 resource
write_index_file(for_versions: resources_by_version.keys)
resources_by_version.each_key do |version|
@seen_components_for_current_version = Set.new
write_version_file(version)
end
end
def initialize
require 'yaml'
@resources_by_version = Hash.new do |h, k|
h[k] = Set.new
end
# List of types that we have seen/marked as necessary to list in the components/schemas section
# These should contain any mediatype define in the versioned controllers plus any type
# for which we've explicitly rendered a $ref schema
@seen_components_for_current_version = Set.new
@infos = ApiDefinition.instance.infos
collect_resources
end
def configure_root(root)
@root = root
end
def register_seen_component(type)
@seen_components_for_current_version.add(type)
end
private
def collect_resources
# load all resource definitions registered with Praxis
Praxis::Application.instance.endpoint_definitions.map do |resource|
# skip resources with doc_visibility of :none
next if resource.metadata[:doc_visibility] == :none
version = resource.version
# TODO: it seems that we shouldn't hardcode n/a in Praxis
# version = "unversioned" if version == "n/a"
@resources_by_version[version] << resource
end
end
def write_index_file(for_versions:)
# TODO. create a simple html file that can link to the individual versions available
end
# TODO: Change this function name to scan_default_mediatypes...
def collect_default_mediatypes(endpoints)
# We'll start by processing the rendered mediatypes
Set.new(endpoints.select do |endpoint|
endpoint.media_type && !endpoint.media_type.is_a?(Praxis::SimpleMediaType)
end.collect(&:media_type))
end
def write_version_file(version)
# version_info = infos_by_version[version]
# # Hack, let's "inherit/copy" all traits of a version from the global definition
# # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
# version_info[:traits] = infos_by_version[:traits]
# We'll for sure include any of the default mediatypes in the endpoints for this version
@seen_components_for_current_version.merge(collect_default_mediatypes(resources_by_version[version]))
# Here we have:
# processed types: which includes default mediatypes for the processed endpoints
# processed resources for this version: resources_by_version[version]
info_object = OpenApi::InfoObject.new(version: version, api_definition_info: @infos[version])
# We only support a server in Praxis ... so we'll use the base path
server_object = OpenApi::ServerObject.new(url: @infos[version].base_path)
paths_object = OpenApi::PathsObject.new(resources: resources_by_version[version])
full_data = {
openapi: '3.0.2',
info: info_object.dump,
servers: [server_object.dump],
paths: paths_object.dump
# responses: {}, #TODO!! what do we get here? the templates?...need to transform to "Responses Definitions Object"
# securityDefinitions: {}, # NOTE: No security definitions in Praxis
# security: [], # NOTE: No security definitions in Praxis
}
# Create the top level tags by:
# 1- First adding all the resource display names (and descriptions)
tags_for_resources = resources_by_version[version].collect do |resource|
OpenApi::TagObject.new(name: resource.display_name, description: resource.description).dump
end
full_data[:tags] = tags_for_resources
# 2- Then adding all of the top level traits but marking them special with the x-traitTag (of Redoc)
tags_for_traits = ApiDefinition.instance.traits.collect do |name, info|
OpenApi::TagObject.new(name: name, description: info.description).dump.merge('x-traitTag': true)
end
full_data[:tags] = full_data[:tags] + tags_for_traits unless tags_for_traits.empty?
# Include only MTs and Blueprints (i.e., no simple types...)
component_schemas = add_component_schemas(@seen_components_for_current_version.clone, {})
# 3- Then adding all of the top level Mediatypes...so we can present them at the bottom, otherwise they don't show
tags_for_mts = component_schemas.map do |(name, _info)|
special_redoc_anchor = ""
guessed_display = name.split('-').last # TODO!!!the informational hash does not seem to come with the "description" value set...hmm
OpenApi::TagObject.new(name: name, description: special_redoc_anchor).dump.merge('x-displayName': guessed_display)
end
full_data[:tags] = full_data[:tags] + tags_for_mts unless tags_for_mts.empty?
# Include all the reusable schemas in the components hash
full_data[:components] = {
schemas: component_schemas
}
# REDOC specific grouping of sidebar
resource_tags = { name: 'Resources', tags: tags_for_resources.map { |t| t[:name] } }
schema_tags = { name: 'Models', tags: tags_for_mts.map { |t| t[:name] } }
full_data['x-tagGroups'] = [resource_tags, schema_tags]
# if parameter_object = convert_to_parameter_object( version_info[:info][:base_params] )
# full_data[:parameters] = parameter_object
# end
# puts JSON.pretty_generate( full_data )
# Write the file
version_file = (version == 'n/a' ? 'unversioned' : version)
filename = File.join(doc_root_dir, version_file, 'openapi')
puts "Generating Open API file : #{filename} (json and yml) "
json_data = JSON.pretty_generate(full_data)
File.open("#{filename}.json", 'w') { |f| f.write(json_data) }
converted_full_data = JSON.parse(json_data) # So symbols disappear
File.open("#{filename}.yml", 'w') { |f| f.write(YAML.dump(converted_full_data)) }
html = <<-HTML
ReDoc
HTML
html_file = File.join(doc_root_dir, version_file, 'index.html')
File.write(html_file, html)
end
def initialize_directories
@doc_root_dir = File.join(@root, API_DOCS_DIRNAME)
# remove previous data (and reset the directory)
FileUtils.rm_rf @doc_root_dir if File.exist?(@doc_root_dir)
FileUtils.mkdir_p @doc_root_dir unless File.exist? @doc_root_dir
resources_by_version.each_key do |version|
FileUtils.mkdir_p "#{@doc_root_dir}/#{version}"
end
FileUtils.mkdir_p "#{@doc_root_dir}/unversioned" if resources_by_version.keys.include?('n/a')
end
def normalize_media_types(mtis)
mtis.collect do |mti|
MediaTypeIdentifier.load(mti).to_s
end
end
def add_component_schemas(types_to_add, components_hash)
initial = @seen_components_for_current_version.dup
types_to_add.each_with_object(components_hash) do |(type), accum|
# For components, we want the first level to be fully dumped (only references below that)
accum[type.id] = OpenApi::SchemaObject.new(info: type).dump_schema(allow_ref: false, shallow: false)
end
newfound = @seen_components_for_current_version - initial
# Process the new types if they have discovered
add_component_schemas(newfound, components_hash) unless newfound.empty?
components_hash
end
def convert_to_parameter_object(params)
# TODO!! actually convert each of them
puts 'TODO! convert to parameter object'
params
end
def convert_traits_to_tags(traits)
traits.collect do |name, info|
{ name: name, description: info[:description] }
end
end
def dump_responses_object(responses)
responses.each_with_object({}) do |(_name, info), hash|
data = { description: info[:description] || '' }
if (payload = info[:payload])
body_type = payload[:id]
raise "WAIT! response payload doesn't have an existing id for the schema!!! (do an if, and describe it if so)" unless body_type
data[:schema] = { '$ref' => "#/definitions/#{body_type}" }
end
# data[:schema] = ???TODO!!
if (headers_object = dump_response_headers_object(info[:headers]))
data[:headers] = headers_object
end
if info[:payload] && (examples_object = dump_response_examples_object(info[:payload][:examples]))
data[:examples] = examples_object
end
hash[info[:status]] = data
end
end
# def dump_response_headers_object( headers )
# puts "WARNING!! Finish this. It seems that headers for responses are never set in the hash??"
# unless headers.empty?
# binding.pry
# puts headers
# end
# end
def dump_response_examples_object(examples)
examples.each_with_object({}) do |(_name, info), hash|
hash[info[:content_type]] = info[:body]
end
end
def dump_resources(resources)
resources.each_with_object({}) do |r, hash|
# Do not report undocumentable resources
next if r.metadata[:doc_visibility] == :none
context = [r.id]
resource_description = r.describe(context: context)
# strip actions with doc_visibility of :none
resource_description[:actions].reject! { |a| a[:metadata][:doc_visibility] == :none }
# Go through the params/payload of each action and augment them by
# adding a generated example (then stick it into the description hash)
r.actions.each do |action_name, action|
# skip actions with doc_visibility of :none
next if action.metadata[:doc_visibility] == :none
resource_description[:actions].find { |a| a[:name] == action_name }
end
hash[r.id] = resource_description
end
end
end
end
end