snippets.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Sander van Harmelen
     3  //
     4  // Licensed under the Apache License, Version 2.0 (the "License");
     5  // you may not use this file except in compliance with the License.
     6  // You may obtain a copy of the License at
     7  //
     8  //     http://www.apache.org/licenses/LICENSE-2.0
     9  //
    10  // Unless required by applicable law or agreed to in writing, software
    11  // distributed under the License is distributed on an "AS IS" BASIS,
    12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  // See the License for the specific language governing permissions and
    14  // limitations under the License.
    15  //
    16  
    17  package gitlab
    18  
    19  import (
    20  	"bytes"
    21  	"fmt"
    22  	"net/http"
    23  	"time"
    24  )
    25  
    26  // SnippetsService handles communication with the snippets
    27  // related methods of the GitLab API.
    28  //
    29  // GitLab API docs: https://docs.gitlab.com/ee/api/snippets.html
    30  type SnippetsService struct {
    31  	client *Client
    32  }
    33  
    34  // Snippet represents a GitLab snippet.
    35  //
    36  // GitLab API docs: https://docs.gitlab.com/ee/api/snippets.html
    37  type Snippet struct {
    38  	ID          int    `json:"id"`
    39  	Title       string `json:"title"`
    40  	FileName    string `json:"file_name"`
    41  	Description string `json:"description"`
    42  	Visibility  string `json:"visibility"`
    43  	Author      struct {
    44  		ID        int        `json:"id"`
    45  		Username  string     `json:"username"`
    46  		Email     string     `json:"email"`
    47  		Name      string     `json:"name"`
    48  		State     string     `json:"state"`
    49  		CreatedAt *time.Time `json:"created_at"`
    50  	} `json:"author"`
    51  	UpdatedAt *time.Time `json:"updated_at"`
    52  	CreatedAt *time.Time `json:"created_at"`
    53  	WebURL    string     `json:"web_url"`
    54  	RawURL    string     `json:"raw_url"`
    55  	Files     []struct {
    56  		Path   string `json:"path"`
    57  		RawURL string `json:"raw_url"`
    58  	} `json:"files"`
    59  	RepositoryStorage string `json:"repository_storage"`
    60  }
    61  
    62  func (s Snippet) String() string {
    63  	return Stringify(s)
    64  }
    65  
    66  // ListSnippetsOptions represents the available ListSnippets() options.
    67  //
    68  // GitLab API docs:
    69  // https://docs.gitlab.com/ee/api/snippets.html#list-all-snippets-for-a-user
    70  type ListSnippetsOptions ListOptions
    71  
    72  // ListSnippets gets a list of snippets.
    73  //
    74  // GitLab API docs:
    75  // https://docs.gitlab.com/ee/api/snippets.html#list-all-snippets-for-a-user
    76  func (s *SnippetsService) ListSnippets(opt *ListSnippetsOptions, options ...RequestOptionFunc) ([]*Snippet, *Response, error) {
    77  	req, err := s.client.NewRequest(http.MethodGet, "snippets", opt, options)
    78  	if err != nil {
    79  		return nil, nil, err
    80  	}
    81  
    82  	var ps []*Snippet
    83  	resp, err := s.client.Do(req, &ps)
    84  	if err != nil {
    85  		return nil, resp, err
    86  	}
    87  
    88  	return ps, resp, nil
    89  }
    90  
    91  // GetSnippet gets a single snippet
    92  //
    93  // GitLab API docs:
    94  // https://docs.gitlab.com/ee/api/snippets.html#get-a-single-snippet
    95  func (s *SnippetsService) GetSnippet(snippet int, options ...RequestOptionFunc) (*Snippet, *Response, error) {
    96  	u := fmt.Sprintf("snippets/%d", snippet)
    97  
    98  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
    99  	if err != nil {
   100  		return nil, nil, err
   101  	}
   102  
   103  	ps := new(Snippet)
   104  	resp, err := s.client.Do(req, ps)
   105  	if err != nil {
   106  		return nil, resp, err
   107  	}
   108  
   109  	return ps, resp, nil
   110  }
   111  
   112  // SnippetContent gets a single snippet’s raw contents.
   113  //
   114  // GitLab API docs:
   115  // https://docs.gitlab.com/ee/api/snippets.html#single-snippet-contents
   116  func (s *SnippetsService) SnippetContent(snippet int, options ...RequestOptionFunc) ([]byte, *Response, error) {
   117  	u := fmt.Sprintf("snippets/%d/raw", snippet)
   118  
   119  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   120  	if err != nil {
   121  		return nil, nil, err
   122  	}
   123  
   124  	var b bytes.Buffer
   125  	resp, err := s.client.Do(req, &b)
   126  	if err != nil {
   127  		return nil, resp, err
   128  	}
   129  
   130  	return b.Bytes(), resp, err
   131  }
   132  
   133  // SnippetFileContent returns the raw file content as plain text.
   134  //
   135  // GitLab API docs:
   136  // https://docs.gitlab.com/ee/api/snippets.html#snippet-repository-file-content
   137  func (s *SnippetsService) SnippetFileContent(snippet int, ref, filename string, options ...RequestOptionFunc) ([]byte, *Response, error) {
   138  	filepath := PathEscape(filename)
   139  	u := fmt.Sprintf("snippets/%d/files/%s/%s/raw", snippet, ref, filepath)
   140  
   141  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   142  	if err != nil {
   143  		return nil, nil, err
   144  	}
   145  
   146  	var b bytes.Buffer
   147  	resp, err := s.client.Do(req, &b)
   148  	if err != nil {
   149  		return nil, resp, err
   150  	}
   151  
   152  	return b.Bytes(), resp, err
   153  }
   154  
   155  // CreateSnippetFileOptions represents the create snippet file options.
   156  //
   157  // GitLab API docs:
   158  // https://docs.gitlab.com/ee/api/snippets.html#create-new-snippet
   159  type CreateSnippetFileOptions struct {
   160  	FilePath *string `url:"file_path,omitempty" json:"file_path,omitempty"`
   161  	Content  *string `url:"content,omitempty" json:"content,omitempty"`
   162  }
   163  
   164  // CreateSnippetOptions represents the available CreateSnippet() options.
   165  //
   166  // GitLab API docs:
   167  // https://docs.gitlab.com/ee/api/snippets.html#create-new-snippet
   168  type CreateSnippetOptions struct {
   169  	Title       *string                      `url:"title,omitempty" json:"title,omitempty"`
   170  	FileName    *string                      `url:"file_name,omitempty" json:"file_name,omitempty"`
   171  	Description *string                      `url:"description,omitempty" json:"description,omitempty"`
   172  	Content     *string                      `url:"content,omitempty" json:"content,omitempty"`
   173  	Visibility  *VisibilityValue             `url:"visibility,omitempty" json:"visibility,omitempty"`
   174  	Files       *[]*CreateSnippetFileOptions `url:"files,omitempty" json:"files,omitempty"`
   175  }
   176  
   177  // CreateSnippet creates a new snippet. The user must have permission
   178  // to create new snippets.
   179  //
   180  // GitLab API docs:
   181  // https://docs.gitlab.com/ee/api/snippets.html#create-new-snippet
   182  func (s *SnippetsService) CreateSnippet(opt *CreateSnippetOptions, options ...RequestOptionFunc) (*Snippet, *Response, error) {
   183  	req, err := s.client.NewRequest(http.MethodPost, "snippets", opt, options)
   184  	if err != nil {
   185  		return nil, nil, err
   186  	}
   187  
   188  	ps := new(Snippet)
   189  	resp, err := s.client.Do(req, ps)
   190  	if err != nil {
   191  		return nil, resp, err
   192  	}
   193  
   194  	return ps, resp, nil
   195  }
   196  
   197  // UpdateSnippetFileOptions represents the update snippet file options.
   198  //
   199  // GitLab API docs:
   200  // https://docs.gitlab.com/ee/api/snippets.html#update-snippet
   201  type UpdateSnippetFileOptions struct {
   202  	Action       *string `url:"action,omitempty" json:"action,omitempty"`
   203  	FilePath     *string `url:"file_path,omitempty" json:"file_path,omitempty"`
   204  	Content      *string `url:"content,omitempty" json:"content,omitempty"`
   205  	PreviousPath *string `url:"previous_path,omitempty" json:"previous_path,omitempty"`
   206  }
   207  
   208  // UpdateSnippetOptions represents the available UpdateSnippet() options.
   209  //
   210  // GitLab API docs:
   211  // https://docs.gitlab.com/ee/api/snippets.html#update-snippet
   212  type UpdateSnippetOptions struct {
   213  	Title       *string                      `url:"title,omitempty" json:"title,omitempty"`
   214  	FileName    *string                      `url:"file_name,omitempty" json:"file_name,omitempty"`
   215  	Description *string                      `url:"description,omitempty" json:"description,omitempty"`
   216  	Content     *string                      `url:"content,omitempty" json:"content,omitempty"`
   217  	Visibility  *VisibilityValue             `url:"visibility,omitempty" json:"visibility,omitempty"`
   218  	Files       *[]*UpdateSnippetFileOptions `url:"files,omitempty" json:"files,omitempty"`
   219  }
   220  
   221  // UpdateSnippet updates an existing snippet. The user must have
   222  // permission to change an existing snippet.
   223  //
   224  // GitLab API docs:
   225  // https://docs.gitlab.com/ee/api/snippets.html#update-snippet
   226  func (s *SnippetsService) UpdateSnippet(snippet int, opt *UpdateSnippetOptions, options ...RequestOptionFunc) (*Snippet, *Response, error) {
   227  	u := fmt.Sprintf("snippets/%d", snippet)
   228  
   229  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   230  	if err != nil {
   231  		return nil, nil, err
   232  	}
   233  
   234  	ps := new(Snippet)
   235  	resp, err := s.client.Do(req, ps)
   236  	if err != nil {
   237  		return nil, resp, err
   238  	}
   239  
   240  	return ps, resp, nil
   241  }
   242  
   243  // DeleteSnippet deletes an existing snippet. This is an idempotent
   244  // function and deleting a non-existent snippet still returns a 200 OK status
   245  // code.
   246  //
   247  // GitLab API docs:
   248  // https://docs.gitlab.com/ee/api/snippets.html#delete-snippet
   249  func (s *SnippetsService) DeleteSnippet(snippet int, options ...RequestOptionFunc) (*Response, error) {
   250  	u := fmt.Sprintf("snippets/%d", snippet)
   251  
   252  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   253  	if err != nil {
   254  		return nil, err
   255  	}
   256  
   257  	return s.client.Do(req, nil)
   258  }
   259  
   260  // ExploreSnippetsOptions represents the available ExploreSnippets() options.
   261  //
   262  // GitLab API docs:
   263  // https://docs.gitlab.com/ee/api/snippets.html#list-all-public-snippets
   264  type ExploreSnippetsOptions ListOptions
   265  
   266  // ExploreSnippets gets the list of public snippets.
   267  //
   268  // GitLab API docs:
   269  // https://docs.gitlab.com/ee/api/snippets.html#list-all-public-snippets
   270  func (s *SnippetsService) ExploreSnippets(opt *ExploreSnippetsOptions, options ...RequestOptionFunc) ([]*Snippet, *Response, error) {
   271  	req, err := s.client.NewRequest(http.MethodGet, "snippets/public", opt, options)
   272  	if err != nil {
   273  		return nil, nil, err
   274  	}
   275  
   276  	var ps []*Snippet
   277  	resp, err := s.client.Do(req, &ps)
   278  	if err != nil {
   279  		return nil, resp, err
   280  	}
   281  
   282  	return ps, resp, nil
   283  }
   284  
   285  // ListAllSnippetsOptions represents the available ListAllSnippets() options.
   286  //
   287  // GitLab API docs:
   288  // https://docs.gitlab.com/ee/api/snippets.html#list-all-snippets
   289  type ListAllSnippetsOptions struct {
   290  	ListOptions
   291  	CreatedAfter      *ISOTime `url:"created_after,omitempty" json:"created_after,omitempty"`
   292  	CreatedBefore     *ISOTime `url:"created_before,omitempty" json:"created_before,omitempty"`
   293  	RepositoryStorage *string  `url:"repository_storage,omitempty" json:"repository_storage,omitempty"`
   294  }
   295  
   296  // ListAllSnippets gets all snippets the current user has access to.
   297  //
   298  // GitLab API docs:
   299  // https://docs.gitlab.com/ee/api/snippets.html#list-all-snippets
   300  func (s *SnippetsService) ListAllSnippets(opt *ListAllSnippetsOptions, options ...RequestOptionFunc) ([]*Snippet, *Response, error) {
   301  	req, err := s.client.NewRequest(http.MethodGet, "snippets/all", opt, options)
   302  	if err != nil {
   303  		return nil, nil, err
   304  	}
   305  
   306  	var ps []*Snippet
   307  	resp, err := s.client.Do(req, &ps)
   308  	if err != nil {
   309  		return nil, resp, err
   310  	}
   311  
   312  	return ps, resp, nil
   313  }
   314
View as plain text