Commit 06329a09 authored by Vitali Tatarintev's avatar Vitali Tatarintev

Merge branch 'ld-graphql-docs-enum' into 'master'

Include enum types in auto-generated GraphQL docs

See merge request gitlab-org/gitlab!41840
parents 4a8eacdb 0febc0a2
This source diff could not be displayed because it is too large. You can view the blob instead.
...@@ -21,30 +21,47 @@ module Gitlab ...@@ -21,30 +21,47 @@ module Gitlab
MD MD
end end
def sorted_fields(fields) def render_name_and_description(object)
fields.sort_by { |field| field[:name] } 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 end
def render_field(field) def render_field(field)
'| %s | %s | %s |' % [ '| %s | %s | %s |' % [
render_field_name(field), render_name(field),
render_field_type(field[:type][:info]), render_field_type(field[:type][:info]),
render_field_description(field) render_description(field)
] ]
end end
def render_field_name(field) def render_enum_value(value)
rendered_name = "`#{field[:name]}`" '| %s | %s |' % [
rendered_name += ' **{warning-solid}**' if field[:is_deprecated] 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 rendered_name
end 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. # the deprecation reason will be returned in place of the description.
def render_field_description(field) def render_description(object)
return field[:description] unless field[:is_deprecated] return object[:description] unless object[:is_deprecated]
"**Deprecated:** #{field[:deprecation_reason]}" "**Deprecated:** #{object[:deprecation_reason]}"
end end
# Some fields types are arrays of other types and are displayed # Some fields types are arrays of other types and are displayed
...@@ -70,6 +87,13 @@ module Gitlab ...@@ -70,6 +87,13 @@ module Gitlab
!object_type[:name]["__"] !object_type[:name]["__"]
end end
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 end
end end
......
...@@ -15,15 +15,45 @@ ...@@ -15,15 +15,45 @@
CAUTION: **Caution:** CAUTION: **Caution:**
Fields that are deprecated are marked with **{warning-solid}**. 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| - objects.each do |type|
- unless type[:fields].empty? - unless type[:fields].empty?
= "## #{type[:name]}" = render_name_and_description(type)
- if type[:description]&.present? ~ "| Field | Type | Description |"
\ ~ "| ----- | ---- | ----------- |"
= type[:description] - sorted_by_name(type[:fields]).each do |field|
\
~ "| Name | Type | Description |"
~ "| --- | ---- | ---------- |"
- sorted_fields(type[:fields]).each do |field|
= render_field(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 ...@@ -36,10 +36,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do specify do
expectation = <<~DOC expectation = <<~DOC
## ArrayTest ### ArrayTest
| Name | Type | Description | | Field | Type | Description |
| --- | ---- | ---------- | | ----- | ---- | ----------- |
| `foo` | String! => Array | A description | | `foo` | String! => Array | A description |
DOC DOC
...@@ -59,10 +59,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do ...@@ -59,10 +59,10 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do specify do
expectation = <<~DOC expectation = <<~DOC
## OrderingTest ### OrderingTest
| Name | Type | Description | | Field | Type | Description |
| --- | ---- | ---------- | | ----- | ---- | ----------- |
| `bar` | String! | A description of bar field | | `bar` | String! | A description of bar field |
| `foo` | String! | A description of foo field | | `foo` | String! | A description of foo field |
DOC DOC
...@@ -82,15 +82,45 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do ...@@ -82,15 +82,45 @@ RSpec.describe Gitlab::Graphql::Docs::Renderer do
specify do specify do
expectation = <<~DOC expectation = <<~DOC
## DeprecatedTest ### DeprecatedTest
| Name | Type | Description | | Field | Type | Description |
| --- | ---- | ---------- | | ----- | ---- | ----------- |
| `foo` **{warning-solid}** | String! | **Deprecated:** This is deprecated. Deprecated in 1.10 | | `foo` **{warning-solid}** | String! | **Deprecated:** This is deprecated. Deprecated in 1.10 |
DOC DOC
is_expected.to include(expectation) is_expected.to include(expectation)
end end
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
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