diff options
Diffstat (limited to 'lib/gitlab/graphql/docs')
-rw-r--r-- | lib/gitlab/graphql/docs/helper.rb | 46 | ||||
-rw-r--r-- | lib/gitlab/graphql/docs/templates/default.md.haml | 46 |
2 files changed, 73 insertions, 19 deletions
diff --git a/lib/gitlab/graphql/docs/helper.rb b/lib/gitlab/graphql/docs/helper.rb index 0dd28b32511..dcd0e12cbfc 100644 --- a/lib/gitlab/graphql/docs/helper.rb +++ b/lib/gitlab/graphql/docs/helper.rb @@ -21,30 +21,47 @@ module Gitlab MD end - def sorted_fields(fields) - fields.sort_by { |field| field[:name] } + def render_name_and_description(object) + content = "### #{object[:name]}\n" + + if object[:description].present? + content += "\n#{object[:description]}.\n" + end + + content + end + + def sorted_by_name(objects) + objects.sort_by { |o| o[:name] } end def render_field(field) '| %s | %s | %s |' % [ - render_field_name(field), + render_name(field), render_field_type(field[:type][:info]), - render_field_description(field) + render_description(field) ] end - def render_field_name(field) - rendered_name = "`#{field[:name]}`" - rendered_name += ' **{warning-solid}**' if field[:is_deprecated] + def render_enum_value(value) + '| %s | %s |' % [ + render_name(value), + render_description(value) + ] + end + + def render_name(object) + rendered_name = "`#{object[:name]}`" + rendered_name += ' **{warning-solid}**' if object[:is_deprecated] rendered_name end - # Returns the field description. If the field has been deprecated, + # Returns the object description. If the object has been deprecated, # the deprecation reason will be returned in place of the description. - def render_field_description(field) - return field[:description] unless field[:is_deprecated] + def render_description(object) + return object[:description] unless object[:is_deprecated] - "**Deprecated:** #{field[:deprecation_reason]}" + "**Deprecated:** #{object[:deprecation_reason]}" end # Some fields types are arrays of other types and are displayed @@ -70,6 +87,13 @@ module Gitlab !object_type[:name]["__"] end end + + # We ignore the built-in enum types. + def enums + graphql_enum_types.select do |enum_type| + !enum_type[:name].in?(%w(__DirectiveLocation __TypeKind)) + end + end end end end diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml index 8c033526557..ec052943589 100644 --- a/lib/gitlab/graphql/docs/templates/default.md.haml +++ b/lib/gitlab/graphql/docs/templates/default.md.haml @@ -15,15 +15,45 @@ CAUTION: **Caution:** Fields that are deprecated are marked with **{warning-solid}**. \ + +:plain + ## Object types + + Object types represent the resources that GitLab's GraphQL API can return. + They contain _fields_. Each field has its own type, which will either be one of the + basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types) + (e.g.: `String` or `Boolean`) or other object types. + + For more information, see + [Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields) + on `graphql.org`. +\ + - objects.each do |type| - unless type[:fields].empty? - = "## #{type[:name]}" - - if type[:description]&.present? - \ - = type[:description] - \ - ~ "| Name | Type | Description |" - ~ "| --- | ---- | ---------- |" - - sorted_fields(type[:fields]).each do |field| + = render_name_and_description(type) + ~ "| Field | Type | Description |" + ~ "| ----- | ---- | ----------- |" + - sorted_by_name(type[:fields]).each do |field| = render_field(field) \ + +:plain + ## Enumeration types + + Also called _Enums_, enumeration types are a special kind of scalar that + is restricted to a particular set of allowed values. + + For more information, see + [Enumeration Types](https://graphql.org/learn/schema/#enumeration-types) + on `graphql.org`. +\ + +- enums.each do |enum| + - unless enum[:values].empty? + = render_name_and_description(enum) + ~ "| Value | Description |" + ~ "| ----- | ----------- |" + - sorted_by_name(enum[:values]).each do |value| + = render_enum_value(value) + \ |