[GPT Actions] 9. GitHub API | Repositories

달의이성2024-07-19 22:30

GitHub API는 매우 광범위하고 복잡하므로, 여기서는 'Repositories' 관련 엔드포인트 몇 가지만 다루겠습니다.

Step 1: 기본 구조 설정

openapi: 3.1.0
info:
  title: GitHub API
  description: Access GitHub's features and data for your applications
  version: "2022-11-28"
  termsOfService: https://docs.github.com/en/github/site-policy/github-terms-of-service
  contact:
    name: GitHub Support
    url: https://support.github.com/
servers:
  - url: https://api.github.com
    description: GitHub API v3
tags:
  - name: repositories
    description: Operations about repositories
paths:
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []

Step 2: 경로(Paths) 정의

paths:
  /repos/{owner}/{repo}:
    get:
      summary: Get a repository
      tags:
        - repositories
      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/Repository'
        '404':
          description: Resource not found
  
  /user/repos:
    get:
      summary: List repositories for the authenticated user
      tags:
        - repositories
      parameters:
        - name: visibility
          in: query
          schema:
            type: string
            enum: [all, public, private]
        - name: sort
          in: query
          schema:
            type: string
            enum: [created, updated, pushed, full_name]
        - name: per_page
          in: query
          schema:
            type: integer
            default: 30
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Repository'
  
  /repos/{owner}/{repo}/issues:
    get:
      summary: List repository issues
      tags:
        - repositories
      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, comments]
            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/Issue'

Step 3: 스키마(Schemas) 정의

components:
  schemas:
    Repository:
      type: object
      properties:
        id:
          type: integer
        node_id:
          type: string
        name:
          type: string
        full_name:
          type: string
        owner:
          $ref: '#/components/schemas/User'
        private:
          type: boolean
        html_url:
          type: string
          format: uri
        description:
          type: string
        fork:
          type: boolean
        url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        pushed_at:
          type: string
          format: date-time
        homepage:
          type: string
        size:
          type: integer
        stargazers_count:
          type: integer
        watchers_count:
          type: integer
        language:
          type: string
        forks_count:
          type: integer
        open_issues_count:
          type: integer
        master_branch:
          type: string
        default_branch:
          type: string
        score:
          type: number
    
    User:
      type: object
      properties:
        login:
          type: string
        id:
          type: integer
        node_id:
          type: string
        avatar_url:
          type: string
          format: uri
        gravatar_id:
          type: string
        url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
        type:
          type: string
        site_admin:
          type: boolean
    
    Issue:
      type: object
      properties:
        id:
          type: integer
        node_id:
          type: string
        url:
          type: string
          format: uri
        repository_url:
          type: string
          format: uri
        labels_url:
          type: string
          format: uri
        comments_url:
          type: string
          format: uri
        events_url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
        number:
          type: integer
        state:
          type: string
        title:
          type: string
        body:
          type: string
        user:
          $ref: '#/components/schemas/User'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        assignee:
          $ref: '#/components/schemas/User'
        assignees:
          type: array
          items:
            $ref: '#/components/schemas/User'
        milestone:
          $ref: '#/components/schemas/Milestone'
        comments:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
        author_association:
          type: string
    
    Label:
      type: object
      properties:
        id:
          type: integer
        node_id:
          type: string
        url:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        color:
          type: string
        default:
          type: boolean
    
    Milestone:
      type: object
      properties:
        url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
        labels_url:
          type: string
          format: uri
        id:
          type: integer
        node_id:
          type: string
        number:
          type: integer
        state:
          type: string
        title:
          type: string
        description:
          type: string
        creator:
          $ref: '#/components/schemas/User'
        open_issues:
          type: integer
        closed_issues:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
        due_on:
          type: string
          format: date-time

Step 4: 예제(Examples) 추가

components:
  schemas:
    Repository:
      # ... (이전 내용 유지)
      example:
        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
        private: false
        html_url: "https://github.com/octocat/Hello-World"
        description: "This your first repo!"
        fork: false
        url: "https://api.github.com/repos/octocat/Hello-World"
        created_at: "2011-01-26T19:01:12Z"
        updated_at: "2011-01-26T19:14:43Z"
        pushed_at: "2011-01-26T19:06:43Z"
        homepage: "https://github.com"
        size: 108
        stargazers_count: 80
        watchers_count: 80
        language: "C"
        forks_count: 9
        open_issues_count: 0
        master_branch: "master"
        default_branch: "master"
        score: 1

이 OpenAPI 스키마는 GitHub API의 'Repositories' 관련 주요 기능 일부를 문서화하고 있습니다. 여기에는 특정 저장소 조회, 인증된 사용자의 저장소 목록 조회, 저장소 이슈 목록 조회 등의 엔드포인트가 포함되어 있습니다. 각 엔드포인트에 대한 파라미터, 응답 스키마, 그리고 가능한 응답 코드들이 정의되어 있습니다.

이 스키마를 사용하면 개발자들이 GitHub API의 이 부분을 쉽게 이해하고 사용할 수 있습니다. Swagger UI나 다른 OpenAPI 호환 도구를 통해 대화형 문서를 생성하고 API를 직접 테스트해볼 수 있습니다.

실제 GitHub API 문서화 작업을 할 때는 이러한 구조를 기반으로 하되, API의 모든 엔드포인트와 기능을 포함하도록 크게 확장해야 합니다. 또한 각 엔드포인트와 파라미터에 대한 더 자세한 설명, 사용 예제, 에러 응답 등을 추가하는 것이 좋습니다.

이러한 복잡한 API를 문서화할 때는 각 리소스 타입(예: repositories, issues, pulls 등)별로 태그를 사용하여 구조화하고, 공통으로 사용되는 파라미터나 응답 형식은 재사용 가능한 컴포넌트로 정의하여 문서의 일관성과 유지보수성을 높이는 것이 중요합니다.