Commit 0febc0a2 authored by Luke Duncalfe's avatar Luke Duncalfe

Include enum types in auto-generated GraphQL docs

https://gitlab.com/gitlab-org/gitlab/-/issues/246751
parent e5e4531c
This source diff could not be displayed because it is too large. You can view the blob instead.
......@@ -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
......
......@@ -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)
\
......@@ -36,10 +36,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do
expectation = <<~DOC
## ArrayTest
### ArrayTest
| Name | Type | Description |
| --- | ---- | ---------- |
| Field | Type | Description |
| ----- | ---- | ----------- |
| `foo` | String! => Array | A description |
DOC
......@@ -59,10 +59,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do
expectation = <<~DOC
## OrderingTest
### OrderingTest
| Name | Type | Description |
| --- | ---- | ---------- |
| Field | Type | Description |
| ----- | ---- | ----------- |
| `bar` | String! | A description of bar field |
| `foo` | String! | A description of foo field |
DOC
......@@ -82,15 +82,45 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do
expectation = <<~DOC
## DeprecatedTest
### DeprecatedTest
| Name | Type | Description |
| --- | ---- | ---------- |
| Field | Type | Description |
| ----- | ---- | ----------- |
| `foo` **{warning-solid}** | String! | **Deprecated:** This is deprecated. Deprecated in 1.10 |
DOC
is_expected.to include(expectation)
end
end
context 'A type with an emum field' do
let(:type) do
enum_type = Class.new(Types::BaseEnum) do
graphql_name 'MyEnum'
value 'BAZ', description: 'A description of BAZ'
value 'BAR', description: 'A description of BAR', deprecation_reason: 'This is deprecated'
end
Class.new(Types::BaseObject) do
graphql_name 'EnumTest'
field :foo, enum_type, null: false, description: 'A description of foo field'
end
end
specify do
expectation = <<~DOC
### MyEnum
| Value | Description |
| ----- | ----------- |
| `BAR` **{warning-solid}** | **Deprecated:** This is deprecated |
| `BAZ` | A description of BAZ |
DOC
is_expected.to include(expectation)
end
end
end
end
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment