github-openapi.yaml

openapi: "3.0.0"
info:
  version: 3.0.0
  title: GitHub API v3
servers:
  - url: https://api.github.com
paths:
  /users:
    get:
      summary: List all GitHub users.
      description: |
        Lists all users, in the order that they signed up on
        GitHub. This list includes personal user accounts and
        organization accounts.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"

  /users/{username}:
    get:
      summary: Get the public profile information for a user.
      description: |
        Get the public profile information for a single user by their
        GitHub username. In this example, we fetch the details for the
        OAI user.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: username
          in: path
          required: true
          description: The username for which to fetch profile details.
          schema:
            type: string
            example: OAI

  /repositories:
    get:
      summary: This provides a dump of every public repository, in the order that they were created.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"

  /repos/{owner}/{repo}/issues:
    get:
      summary: List issues for a repository.
      description: |
        This endpoint is used to list the issues for given
        repository. In this example, we request all issues for the OAI
        OpenAPI-Specification repository. Optional query parameters
        may be applied to further filter the issues returned.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: owner
          in: path
          required: true
          description: The username of the owner of the repository
          schema:
            type: string
            example: OAI
        - name: repo
          in: path
          required: true
          description: The name of the repository that contains the issue.
          schema:
            type: string
            example: OpenAPI-Specification
        - name: milestone
          in: query
          description: |
            If an integer is passed, it should refer to a milestone by
            its number field. If the string * is passed, issues with
            any milestone are accepted. If the string none is passed,
            issues without milestones are returned.
          schema:
            type: string
        - name: state
          in: query
          description: |
            "Indicates the state of the issues to return. Can be
            either open, closed, or all. Default: open"
          schema:
            type: string
            default: open
        - name: assignee
          in: query
          description: |
            Can be the name of a user. Pass in none for issues with
            no assigned user, and * for issues assigned to any user.
          schema:
            type: string
            default: "*"
        - name: creator
          in: query
          description: The user that created the issue.
          schema:
            type: string
        - name: mentioned
          in: query
          description: A user that was mentioned in the issue
          schema:
            type: string
        - name: labels
          in: query
          description: "A list of comma separated label names. Example: bug,ui,@high"
          schema:
            type: string
        - name: sort
          in: query
          description: |
            "What to sort results by. Can be either created, updated,
            comments. Default: created"
          schema:
            type: string
            default: created
        - name: direction
          in: query
          description: |
            "The direction of the sort. Can be either asc or desc. Default: desc"
          schema:
            type: string
            default: desc
        - name: since
          in: query
          description: |
            "Only issues updated at or after this time are
            returned. This is a timestamp in ISO 8601 format:
            YYYY-MM-DDTHH:MM:SSZ."
          schema:
            type: string

  /repos/{owner}/{repo}/issues/{number}/reactions:
    get:
      summary: List reactions for an issue.
      description: |
        List the reactions for an issue. In this example, we look at
        an issue on the OpenApi-Specification repo that has the most
        +1 reactions.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: Accept
          in: header
          description: |
            APIs for managing reactions are currently available for
            developers to preview. During the preview period, the APIs
            may change without advance notice.  To access the API you
            must provide a custom media type in the Accept header.
          required: true
          schema:
            type: string
            example: "application/vnd.github.squirrel-girl-preview+json"
        - name: owner
          in: path
          required: true
          description: The username of the owner of the repository.
          schema:
            type: string
            example: OAI
        - name: repo
          in: path
          required: true
          description: The name of the repository that contains the issue.
          schema:
            type: string
            example: OpenAPI-Specification
        - name: number
          in: path
          required: true
          description: The issue number for which to list reactions.
          schema:
            type: string
            example: 256
        - name: content
          in: query
          description: Indicates which type of reaction to return.
          schema:
            type: string
            default: "+1"

  /orgs/{org}/repos:
    get:
      summary: List repositories for the specified org.
      description: |
        List repositories for the specified org. The default
        parameters will show all **public** repositories for the OAI
        organization.

        An additional `type` parameter can be specified to further
        filter the repositories returned by the query.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: org
          in: path
          required: true
          description: The organization for which to fetch repositories
          schema:
            type: string
            example: OAI
        - name: type
          in: query
          description: |
            "The types of respositories to fetch. Can be one of `all`,
            `public`, `private`, `forks`, `sources`,
            `member`. Default: `all`"
          schema:
            type: string
            default: all

  /search/commits:
    get:
      summary: Find commits via various criteria. This method returns up to 100 results per page.
      description: |
        Find commits via various criteria. This method returns up to
        100 results per page. This endpoint is configured to find
        commits referencing `open api`, sorted by the best match
        descending.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: Accept
          in: header
          description: |
            The Commit Search API is currently available for
            developers to preview. During the preview period, the APIs
            may change without advance notice.  To access the API you
            must provide a custom media type in the Accept header.
          required: true
          schema:
            type: string
            example: "application/vnd.github.cloak-preview"
        - name: q
          in: query
          required: true
          description: The search terms on which to filter commits.
          schema:
            type: string
            example: open api
        - name: sort
          in: query
          description: |
            "The sort field. Can be author-date or
            committer-date. Default: results are sorted by best
            match."
          schema:
            type: string
        - name: order
          in: query
          description: |
            "The sort order if sort parameter is provided. One of asc
            or desc. Default: desc"
          schema:
            type: string
            default: desc

  /gitignore/templates:
    get:
      summary: List all templates available to pass as an option when creating a repository.
      description: |
        This endpoint lists all of the available `.gitignore`
        templates to pass as options when creating a repository.  It
        simply returns an array of programming language
        names. Additionall, this request could be made into a setup
        step that populates data for a request to the
        `/gitignore/templates/{language}` endpoint.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"

  /gitignore/templates/{language}:
    get:
      summary: Fetch a .gitignore template for a specific language
      description: |
        This endpoint allows fetching a .gitignore template for a
        specific language. When a new repo is created in GitHub, you
        can specify a .gitignore template to apply to the repo. This
        API lists and fetches those templates. In this example, we
        fetch the `.gitignore` template for `Haskell` code-bases.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: language
          in: path
          description: |
            The language to use when fetching a specific `.gitignore`
            template.
          required: true
          schema:
            type: string
            example: Haskell

  /orgs/{org}/members:
    get:
      summary: List all users who are members of an organization.
      description: |
        List all users who are members of an organization. If the
        authenticated user is also a member of this organization then
        both concealed and public members will be returned.

        In this example, we get all of the _public members_ of the OAI
        organization. Additional `filter` and `role` parameters can be
        specified to get public members matching a specific criteria.
      parameters:
        - $ref: "#/components/parameters/userAgentHeader"
        - name: org
          in: path
          description: |
            The name of the organization on which to check if
            `username` is a public member.
          required: true
          schema:
            type: string
            example: OAI
        - name: filter
          in: query
          description: |
            "Filter members returned in the list. Can be one of:
             * 2fa_disabled - Members without two-factor
               authentication enabled. Available for organization
               owners.
             * all - All members the authenticated user can see."
          schema:
            type: string
            default: all
        - name: role
          in: query
          description: |
            "Filter members returned by their role. Can be one of:
            * all - All members of the organization, regardless of role.
            * admin - Organization owners.
            * member - Non-owner organization members.
            Default: all"
          schema:
            type: string
            default: all

components:
  parameters:
    userAgentHeader:
      name: User-Agent
      in: header
      description: |
        All API requests MUST include a valid `User-Agent`
        header. Requests with no `User-Agent` header will be
        rejected. We request that you use your GitHub username, or the
        name of your application, for the User-Agent header
        value. This allows us to contact you if there are problems.
      required: true
      schema:
        type: string
        example: "Assertible-Test-Runner/1.0"