From 45e539eaccb99b67e3eaf6843659e77398025374 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Thu, 23 Dec 2021 17:00:31 +0000 Subject: [PATCH] api/graph: use GraphQL descriptions for docs --- api/graph/schema.graphqls | 140 ++++++++++++++++++++++---------------- 1 file changed, 81 insertions(+), 59 deletions(-) diff --git a/api/graph/schema.graphqls b/api/graph/schema.graphqls index e08a104..924c111 100644 --- a/api/graph/schema.graphqls +++ b/api/graph/schema.graphqls @@ -5,7 +5,7 @@ scalar Binary # base64'd string scalar Cursor scalar File -# Used to provide a human-friendly description of an access scope +"Used to provide a human-friendly description of an access scope" directive @scopehelp(details: String!) on ENUM_VALUE enum AccessScope { @@ -20,12 +20,16 @@ enum AccessKind { RW @scopehelp(details: "read and write") } -# Decorates fields for which access requires a particular OAuth 2.0 scope with -# read or write access. +""" +Decorates fields for which access requires a particular OAuth 2.0 scope with +read or write access. +""" directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION -# This used to decorate private resolvers which are only accessible to build -# workers, and are used to faciliate the build process. +""" +This used to decorate private resolvers which are only accessible to build +workers, and are used to faciliate the build process. +""" directive @worker on FIELD_DEFINITION # https://semver.org @@ -34,9 +38,11 @@ type Version { minor: Int! patch: Int! - # If this API version is scheduled for deprecation, this is the date on which - # it will stop working; or null if this API version is not scheduled for - # deprecation. + """ + If this API version is scheduled for deprecation, this is the date on which + it will stop working; or null if this API version is not scheduled for + deprecation. + """ deprecationDate: Time } @@ -44,8 +50,10 @@ interface Entity { id: Int! created: Time! updated: Time! - # The canonical name of this entity. For users, this is their username - # prefixed with '~'. Additional entity types will be supported in the future. + """ + The canonical name of this entity. For users, this is their username + prefixed with '~'. Additional entity types will be supported in the future. + """ canonicalName: String! } @@ -60,7 +68,7 @@ type User implements Entity { location: String bio: String - # Jobs submitted by this user. + "Jobs submitted by this user." jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO) } @@ -83,11 +91,13 @@ type Job { note: String tags: [String]! - # Name of the build image + "Name of the build image" image: String! - # Name of the build runner which picked up this job, or null if the job is - # pending or queued. + """ + Name of the build runner which picked up this job, or null if the job is + pending or queued. + """ runner: String owner: Entity! @access(scope: PROFILE, kind: RO) @@ -95,37 +105,41 @@ type Job { tasks: [Task]! artifacts: [Artifact]! - # The job's top-level log file, not associated with any tasks + "The job's top-level log file, not associated with any tasks" log: Log @access(scope: LOGS, kind: RO) - # List of secrets available to this job, or null if they were disabled + "List of secrets available to this job, or null if they were disabled" secrets: [Secret] @access(scope: SECRETS, kind: RO) } type Log { - # The most recently written 128 KiB of the build log. + "The most recently written 128 KiB of the build log." last128KiB: String! - # The URL at which the full build log can be downloaded with a GET request - # (text/plain). + """ + The URL at which the full build log can be downloaded with a GET request + (text/plain). + """ fullURL: String! } type Artifact { id: Int! created: Time! - # Original path in the guest + "Original path in the guest" path: String! - # Size in bytes + "Size in bytes" size: Int! - # URL at which the artifact may be downloaded, or null if pruned + "URL at which the artifact may be downloaded, or null if pruned" url: String } -# A cursor for enumerating a list of jobs -# -# If there are additional results available, the cursor object may be passed -# back into the same endpoint to retrieve another page. If the cursor is null, -# there are no remaining results to return. +""" +A cursor for enumerating a list of jobs + +If there are additional results available, the cursor object may be passed +back into the same endpoint to retrieve another page. If the cursor is null, +there are no remaining results to return. +""" type JobCursor { results: [Job!]! cursor: Cursor @@ -164,9 +178,11 @@ enum TriggerCondition { ALWAYS } -# Triggers run upon the completion of all of the jobs in a job group. Note that -# these triggers are distinct from the ones defined by an individual job's -# build manifest, but are similar in functionality. +""" +Triggers run upon the completion of all of the jobs in a job group. Note that +these triggers are distinct from the ones defined by an individual job's +build manifest, but are similar in functionality. +""" interface Trigger { condition: TriggerCondition! } @@ -190,11 +206,13 @@ interface Secret { name: String } -# A cursor for enumerating a list of secrets -# -# If there are additional results available, the cursor object may be passed -# back into the same endpoint to retrieve another page. If the cursor is null, -# there are no remaining results to return. +""" +A cursor for enumerating a list of secrets + +If there are additional results available, the cursor object may be passed +back into the same endpoint to retrieve another page. If the cursor is null, +there are no remaining results to return. +""" type SecretCursor { results: [Secret!]! cursor: Cursor @@ -227,23 +245,23 @@ type SecretFile implements Secret { } type Query { - # Returns API version information. + "Returns API version information." version: Version! - # Returns the authenticated user. + "Returns the authenticated user." me: User! @access(scope: PROFILE, kind: RO) - # Returns a specific user + "Returns a specific user." userByID(id: Int!): User @access(scope: PROFILE, kind: RO) userByName(username: String!): User @access(scope: PROFILE, kind: RO) - # Returns jobs submitted by the authenticated user. + "Returns jobs submitted by the authenticated user." jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO) - # Returns information about a specific job. + "Returns information about a specific job." job(id: Int!): Job @access(scope: JOBS, kind: RO) - # Returns secrets owned by the authenticated user. + "Returns secrets owned by the authenticated user." secrets(cursor: Cursor): SecretCursor! @access(scope: SECRETS, kind: RO) } @@ -270,44 +288,48 @@ input TriggerInput { } type Mutation { - # Submits a new job to the queue. - # - # 'secrets' may be set to false to disable secrets for this build. Secrets - # are enabled if unspecified. - # - # 'execute' may be set to false to defer queueing this job. Builds are - # executed immediately if unspecified. + """ + Submits a new job to the queue. + + 'secrets' may be set to false to disable secrets for this build. Secrets + are enabled if unspecified. + + 'execute' may be set to false to defer queueing this job. Builds are + executed immediately if unspecified. + """ submit(manifest: String!, tags: [String!] note: String, secrets: Boolean, execute: Boolean): Job! @access(scope: JOBS, kind: RW) - # Queues a pending job. + "Queues a pending job." start(jobID: Int!): Job @access(scope: JOBS, kind: RW) - # Cancels a submitted job. + "Cancels a submitted job." cancel(jobId: Int!): Job @access(scope: JOBS, kind: RW) - # Creates a job group from several pending jobs. - # - # 'execute' may be set to false to defer queueing this job. The job group is - # executed immediately if unspecified. + """ + Creates a job group from several pending jobs. + + 'execute' may be set to false to defer queueing this job. The job group is + executed immediately if unspecified. + """ createGroup(jobIds: [Int!]! triggers: [TriggerInput!], execute: Boolean, note: String): JobGroup! @access(scope: JOBS, kind: RW) - # Starts a pending job group. + "Starts a pending job group." startGroup(groupId: Int!): JobGroup @access(scope: JOBS, kind: RW) ### ### The following resolvers are for internal worker use - # Claims a job + "Claims a job." claim(jobId: Int!): Job @worker - # Updates job status + "Updates job status." updateJob(jobId: Int!, status: JobStatus!): Job @worker - # Updates task status + "Updates task status." updateTask(taskId: Int!, status: TaskStatus!): Job @worker - # Uploads a build artifact + "Uploads a build artifact." createArtifact(jobId: Int!, path: String!, contents: File!): Artifact @worker } -- 2.38.5