[GPT Actions] 10. GitHub API | 'Pull Requests'와 'Actions'

공개 노트 검색

회원가입 로그인

GPT ACTIONS

[GPT Actions] 10. GitHub API | 'Pull Requests'와 'Actions'

GitHub API의 문서화를 계속 진행하겠습니다. 이번에는 'Pull Requests'와 'Actions' 관련 엔드포인트를 추가하고, 더 많은 고급 기능을 활용해 보겠습니다.

Step 5: 새로운 태그와 경로 추가

tags:
  # ... (이전 태그들 유지)
  - name: pull_requests
    description: Operations about pull requests
  - name: actions
    description: Operations about GitHub Actions

paths:
  # ... (이전 경로들 유지)

  /repos/{owner}/{repo}/pulls:
    get:
      summary: List pull requests
      tags:
        - pull_requests
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: repo
          in: path
          required: true
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
            enum: [open, closed, all]
            default: open
        - name: sort
          in: query
          schema:
            type: string
            enum: [created, updated, popularity, long-running]
            default: created
        - name: direction
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PullRequest'
  
  /repos/{owner}/{repo}/actions/workflows:
    get:
      summary: List repository workflows
      tags:
        - actions
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: repo
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowList'

Step 6: 새로운 스키마 정의 추가

components:
  schemas:
    # ... (이전 스키마들 유지)

    PullRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
        id:
          type: integer
        node_id:
          type: string
        html_url:
          type: string
          format: uri
        diff_url:
          type: string
          format: uri
        patch_url:
          type: string
          format: uri
        issue_url:
          type: string
          format: uri
        number:
          type: integer
        state:
          type: string
        locked:
          type: boolean
        title:
          type: string
        user:
          $ref: '#/components/schemas/User'
        body:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
        merged_at:
          type: string
          format: date-time
        merge_commit_sha:
          type: string
        assignee:
          $ref: '#/components/schemas/User'
        assignees:
          type: array
          items:
            $ref: '#/components/schemas/User'
        requested_reviewers:
          type: array
          items:
            $ref: '#/components/schemas/User'
        head:
          $ref: '#/components/schemas/PullRequestBranch'
        base:
          $ref: '#/components/schemas/PullRequestBranch'

    PullRequestBranch:
      type: object
      properties:
        label:
          type: string
        ref:
          type: string
        sha:
          type: string
        user:
          $ref: '#/components/schemas/User'
        repo:
          $ref: '#/components/schemas/Repository'

    WorkflowList:
      type: object
      properties:
        total_count:
          type: integer
        workflows:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'

    Workflow:
      type: object
      properties:
        id:
          type: integer
        node_id:
          type: string
        name:
          type: string
        path:
          type: string
        state:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
        badge_url:
          type: string
          format: uri

Step 7: 응답 예제 추가

components:
  schemas:
    PullRequest:
      # ... (이전 속성들 유지)
      example:
        url: "https://api.github.com/repos/octocat/Hello-World/pulls/1347"
        id: 1
        node_id: "MDExOlB1bGxSZXF1ZXN0MQ=="
        html_url: "https://github.com/octocat/Hello-World/pull/1347"
        diff_url: "https://github.com/octocat/Hello-World/pull/1347.diff"
        patch_url: "https://github.com/octocat/Hello-World/pull/1347.patch"
        issue_url: "https://api.github.com/repos/octocat/Hello-World/issues/1347"
        number: 1347
        state: "open"
        locked: false
        title: "Amazing new feature"
        user:
          login: "octocat"
          id: 1
          node_id: "MDQ6VXNlcjE="
          avatar_url: "https://github.com/images/error/octocat_happy.gif"
          gravatar_id: ""
          url: "https://api.github.com/users/octocat"
          html_url: "https://github.com/octocat"
          type: "User"
          site_admin: false
        body: "Please pull these awesome changes in!"
        created_at: "2011-01-26T19:01:12Z"
        updated_at: "2011-01-26T19:01:12Z"
        closed_at: null
        merged_at: null
        merge_commit_sha: null
        assignee: null
        assignees: []
        requested_reviewers: []
        head:
          label: "octocat:new-topic"
          ref: "new-topic"
          sha: "6dcb09b5b57875f334f61aebed695e2e4193db5e"
          user:
            login: "octocat"
            id: 1
            node_id: "MDQ6VXNlcjE="
            avatar_url: "https://github.com/images/error/octocat_happy.gif"
            gravatar_id: ""
            url: "https://api.github.com/users/octocat"
            html_url: "https://github.com/octocat"
            type: "User"
            site_admin: false
          repo:
            id: 1296269
            node_id: "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
            name: "Hello-World"
            full_name: "octocat/Hello-World"
            owner:
              login: "octocat"
              id: 1
              node_id: "MDQ6VXNlcjE="
              avatar_url: "https://github.com/images/error/octocat_happy.gif"
              gravatar_id: ""
              url: "https://api.github.com/users/octocat"
              html_url: "https://github.com/octocat"
              type: "User"
              site_admin: false
        base:
          label: "octocat:master"
          ref: "master"
          sha: "6dcb09b5b57875f334f61aebed695e2e4193db5e"
          user:
            login: "octocat"
            id: 1
            node_id: "MDQ6VXNlcjE="
            avatar_url: "https://github.com/images/error/octocat_happy.gif"
            gravatar_id: ""
            url: "https://api.github.com/users/octocat"
            html_url: "https://github.com/octocat"
            type: "User"
            site_admin: false
          repo:
            id: 1296269
            node_id: "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
            name: "Hello-World"
            full_name: "octocat/Hello-World"
            owner:
              login: "octocat"
              id: 1
              node_id: "MDQ6VXNlcjE="
              avatar_url: "https://github.com/images/error/octocat_happy.gif"
              gravatar_id: ""
              url: "https://api.github.com/users/octocat"
              html_url: "https://github.com/octocat"
              type: "User"
              site_admin: false

    WorkflowList:
      # ... (이전 속성들 유지)
      example:
        total_count: 2
        workflows:
          - id: 161335
            node_id: "MDg6V29ya2Zsb3cxNjEzMzU="
            name: "CI"
            path: ".github/workflows/blank.yml"
            state: "active"
            created_at: "2020-01-08T23:48:37.000-08:00"
            updated_at: "2020-01-08T23:50:21.000-08:00"
            url: "https://api.github.com/repos/octocat/Hello-World/actions/workflows/161335"
            html_url: "https://github.com/octocat/Hello-World/blob/master/.github/workflows/161335"
            badge_url: "https://github.com/octocat/Hello-World/workflows/CI/badge.svg"
          - id: 269289
            node_id: "MDE4OldvcmtmbG93IFNlY29uZGFyeTI2OTI4OQ=="
            name: "Linter"
            path: ".github/workflows/linter.yml"
            state: "active"
            created_at: "2020-01-08T23:48:37.000-08:00"
            updated_at: "2020-01-08T23:50:21.000-08:00"
            url: "https://api.github.com/repos/octocat/Hello-World/actions/workflows/269289"
            html_url: "https://github.com/octocat/Hello-World/blob/master/.github/workflows/269289"
            badge_url: "https://github.com/octocat/Hello-World/workflows/Linter/badge.svg"

Step 8: 보안 스키마 개선

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://github.com/login/oauth/authorize
          tokenUrl: https://github.com/login/oauth/access_token
          scopes:
            repo: Full control of private repositories
            user: Read all user profile data
            workflow: Update GitHub Action workflows

security:
  - BearerAuth: []
  - OAuth2:
      - repo
      - user
      - workflow

이렇게 확장된 OpenAPI 스키마는 GitHub API의 더 많은 기능을 포함하고 있습니다. Pull Requests와 GitHub Actions 관련 엔드포인트가 추가되었고, 각각에 대한 상세한 스키마와 예제가 포함되어 있습니다.

또한 OAuth2 인증 방식이 추가되어, API 사용자가 더 세분화된 권한 관리를 할 수 있게 되었습니다.

이런 방식으로 API 문서를 작성하면 다음과 같은 이점이 있습니다:

구조화된 문서: 각 엔드포인트, 파라미터, 응답 형식이 명확하게 정의됩니다.
일관성: 모든 엔드포인트가 동일한 형식으로 문서화됩니다.
예제 제공: 실제 응답 예제를 통해 API 사용자의 이해를 돕습니다.
보안 정보: API 사용에 필요한 인증 방식이 명확히 기술됩니다.
테스트 용이성: Swagger UI 등의 도구를 통해 API를 직접 테스트할 수 있습니다.

실제 GitHub API는 이보다 훨씬 더 많은 엔드포인트와 기능을 가지고 있습니다. 완전한 문서화를 위해서는 모든 엔드포인트, 파라미터, 응답 형식, 에러 케이스 등을 상세히 기술해야 합니다. 또한 각 기능에 대한 사용 예제, 주의사항, 권한 요구사항 등의 추가 정보도 포함하면 좋습니다.

이러한 방식으로 API 문서를 작성하면, 개발자들이 API를 더 쉽게 이해하고 효과적으로 사용할 수 있게 됩니다.