From 1722324c7bd06b1f9e0a8df90192c68de5769e84 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Mon, 10 Jan 2022 13:31:25 +0000 Subject: [PATCH] api/graph: use GraphQL descriptions for docs --- api/graph/schema.graphqls | 222 ++++++++++++++++++++++---------------- 1 file changed, 128 insertions(+), 94 deletions(-) diff --git a/api/graph/schema.graphqls b/api/graph/schema.graphqls index 7c3374d..ddeb50a 100644 --- a/api/graph/schema.graphqls +++ b/api/graph/schema.graphqls @@ -4,7 +4,7 @@ scalar Cursor scalar Time scalar Upload -# 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 { @@ -19,8 +19,10 @@ 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 # https://semver.org @@ -29,41 +31,43 @@ 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 - # Optional features + "Optional features" features: Features! - # Config settings + "Config settings" settings: Settings! } -# Describes the status of optional features +"Describes the status of optional features" type Features { artifacts: Boolean! } -# Instance specific settings +"Instance specific settings" type Settings { sshUser: String! } enum AccessMode { - # Read-only + "Read-only" RO - # Read/write + "Read/write" RW } enum Visibility { - # Visible to everyone, listed on your profile + "Visible to everyone, listed on your profile" PUBLIC - # Visible to everyone (if they know the URL), not listed on your profile + "Visible to everyone (if they know the URL), not listed on your profile" UNLISTED - # Not visible to anyone except those explicitly added to the access list + "Not visible to anyone except those explicitly added to the access list" PRIVATE } @@ -71,8 +75,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! repositories(cursor: Cursor, filter: Filter): RepositoryCursor! @access(scope: REPOSITORIES, kind: RO) @@ -101,14 +107,18 @@ type Repository { description: String visibility: Visibility! - # The repository's custom README, if set. - # - # NOTICE: This returns unsanitized HTML. It is the client's responsibility to - # sanitize this for display on the web, if so desired. + """ + The repository's custom README, if set. + + NOTICE: This returns unsanitized HTML. It is the client's responsibility to + sanitize this for display on the web, if so desired. + """ readme: String - # If this repository was cloned from another, this is set to the original - # clone URL. + """ + If this repository was cloned from another, this is set to the original + clone URL. + """ upstreamUrl: String accessControlList(cursor: Cursor): ACLCursor! @access(scope: ACLS, kind: RO) @@ -121,80 +131,94 @@ type Repository { ## Porcelain API: # NOTE: revspecs are git-compatible, e.g. "HEAD~4", "master", "9790b10") - - # The HEAD reference for this repository (equivalent to the default branch) + + "The HEAD reference for this repository (equivalent to the default branch)" HEAD: Reference @access(scope: OBJECTS, kind: RO) - # Returns a list of comments sorted by committer time (similar to `git log`'s - # default ordering). - # - # If `from` is specified, it is interpreted as a revspec to start logging - # from. A clever reader may notice that using commits[-1].from + "^" as the - # from parameter is equivalent to passing the cursor to the next call. + """ + Returns a list of comments sorted by committer time (similar to `git log`'s + default ordering). + + If `from` is specified, it is interpreted as a revspec to start logging + from. A clever reader may notice that using commits[-1].from + "^" as the + from parameter is equivalent to passing the cursor to the next call. + """ log(cursor: Cursor, from: String): CommitCursor! @access(scope: OBJECTS, kind: RO) - # Returns a tree entry for a given path, at the given revspec. + "Returns a tree entry for a given path, at the given revspec." path(revspec: String = "HEAD", path: String!): TreeEntry @access(scope: OBJECTS, kind: RO) - # Returns the commit for a given revspec. + "Returns the commit for a given revspec." revparse_single(revspec: String!): Commit @access(scope: OBJECTS, kind: RO) } -# A cursor for enumerating a list of repositories -# -# 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 repositories + +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 RepositoryCursor { results: [Repository!]! cursor: Cursor } -# A cursor for enumerating access control list entries -# -# 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 access control list entries + +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 ACLCursor { results: [ACL!]! cursor: Cursor } -# A cursor for enumerating a list of references -# -# 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 references + +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 ReferenceCursor { results: [Reference!]! cursor: Cursor } -# A cursor for enumerating commits -# -# 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 commits + +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 CommitCursor { results: [Commit!]! cursor: Cursor } -# A cursor for enumerating tree entries -# -# 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 tree entries + +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 TreeEntryCursor { results: [TreeEntry!]! cursor: Cursor } -# A cursor for enumerating artifacts -# -# 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 artifacts + +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 ArtifactCursor { results: [Artifact!]! cursor: Cursor @@ -208,7 +232,7 @@ type ACL { mode: AccessMode } -# Arbitrary file attached to a git repository +"Arbitrary file attached to a git repository" type Artifact { id: Int! created: Time! @@ -237,7 +261,7 @@ interface Object { type: ObjectType! id: String! shortId: String! - # Raw git object, base64 encoded + "Raw git object, base64 encoded" raw: String! } @@ -275,7 +299,7 @@ type TreeEntry { id: String! name: String! object: Object! - # Unix-style file mode, i.e. 0755 or 0644 (octal) + "Unix-style file mode, i.e. 0755 or 0644 (octal)" mode: Int! } @@ -315,41 +339,47 @@ type Tag implements Object { } input Filter { - # Number of results to return. + "Number of results to return." count: Int = 20 - # Search terms. The exact meaning varies by usage, but generally these are - # compatible with the web UI's search syntax. + """ + Search terms. The exact meaning varies by usage, but generally these are + compatible with the web UI's search syntax. + """ search: String } 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." user(username: String!): User @access(scope: PROFILE, kind: RO) - # Returns repositories that the authenticated user has access to. - # - # NOTE: in this version of the API, only repositories owned by the - # authenticated user are returned, but in the future the default behavior - # will be to return all repositories that the user either (1) has been given - # explicit access to via ACLs or (2) has implicit access to either by - # ownership or group membership. + """ + Returns repositories that the authenticated user has access to. + + NOTE: in this version of the API, only repositories owned by the + authenticated user are returned, but in the future the default behavior + will be to return all repositories that the user either (1) has been given + explicit access to via ACLs or (2) has implicit access to either by + ownership or group membership. + """ repositories(cursor: Cursor, filter: Filter): RepositoryCursor @access(scope: REPOSITORIES, kind: RO) - # Returns a specific repository by ID. + "Returns a specific repository by ID." repository(id: Int!): Repository @access(scope: REPOSITORIES, kind: RO) - # Returns a specific repository, owned by the authenticated user. + "Returns a specific repository, owned by the authenticated user." repositoryByName(name: String!): Repository @access(scope: REPOSITORIES, kind: RO) - # Returns a specific repository, owned by the given canonical name (e.g. - # "~sircmpwn"). + """ + Returns a specific repository, owned by the given canonical name (e.g. + "~sircmpwn"). + """ repositoryByOwner(owner: String!, repo: String!): Repository @access(scope: REPOSITORIES, kind: RO) } @@ -360,32 +390,36 @@ input RepoInput { description: String visibility: Visibility - # Updates the custom README associated with this repository. Note that the - # provided HTML will be sanitized when displayed on the web; see - # https://man.sr.ht/markdown/#post-processing + """ + Updates the custom README associated with this repository. Note that the + provided HTML will be sanitized when displayed on the web; see + https://man.sr.ht/markdown/#post-processing + """ readme: String } type Mutation { - # Creates a new git repository + "Creates a new git repository" createRepository(name: String!, visibility: Visibility!, description: String): Repository @access(scope: REPOSITORIES, kind: RW) - # Updates the metadata for a git repository + "Updates the metadata for a git repository" updateRepository(id: Int!, input: RepoInput!): Repository @access(scope: REPOSITORIES, kind: RW) - # Deletes a git repository + "Deletes a git repository" deleteRepository(id: Int!): Repository @access(scope: REPOSITORIES, kind: RW) - # Adds or updates a user in the access control list + "Adds or updates a user in the access control list" updateACL(repoId: Int!, mode: AccessMode!, entity: ID!): ACL! @access(scope: ACLS, kind: RW) - # Deletes an entry from the access control list + "Deletes an entry from the access control list" deleteACL(id: Int!): ACL @access(scope: ACLS, kind: RW) - # Uploads an artifact. revspec must match a specific git tag, and the - # filename must be unique among artifacts for this repository. + """ + Uploads an artifact. revspec must match a specific git tag, and the + filename must be unique among artifacts for this repository. + """ uploadArtifact(repoId: Int!, revspec: String!, file: Upload!): Artifact! @access(scope: OBJECTS, kind: RW) - # Deletes an artifact. + "Deletes an artifact." deleteArtifact(id: Int!): Artifact @access(scope: OBJECTS, kind: RW) } -- 2.38.4