diff --git a/docs/src/main/resources/microsite/data/menu.yml b/docs/src/main/resources/microsite/data/menu.yml index 44135b06e..fc84444b9 100644 --- a/docs/src/main/resources/microsite/data/menu.yml +++ b/docs/src/main/resources/microsite/data/menu.yml @@ -2,5 +2,8 @@ options: - title: Getting Started url: docs.html + - title: Issue API + url: issue.html + - title: Status API url: status.html \ No newline at end of file diff --git a/docs/src/main/tut/issue.md b/docs/src/main/tut/issue.md new file mode 100644 index 000000000..5b8083fd4 --- /dev/null +++ b/docs/src/main/tut/issue.md @@ -0,0 +1,141 @@ +--- +layout: docs +title: Issue API +--- + +# Issue API + +Github4s supports the [Issue API](https://developer.github.com/v3/issues/). As a result, +with github4s, you can: + +- [create an issue](#create-an-issue) +- [edit an issue](#edit-an-issue) +- [list issues](#list-issues) +- [search issues](#search-issues) + +The following examples assume the following imports and token: + +```tut:silent +import github4s.Github +import github4s.Github._ +import github4s.jvm.Implicits._ +import scalaj.http.HttpResponse +// if you're using ScalaJS, replace occurrences of HttpResponse by SimpleHttpResponse +//import github4s.js.Implicits._ +//import fr.hmil.roshttp.response.SimpleHttpResponse + +val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN") +``` + +They also make use of `cats.Id` but any type container implementing `MonadError[M, Throwable]` will +do. + +Support for `cats.Id`, `cats.Eval` and `Future` (the only supported option for scala-js) are +provided out of the box when importing `github4s.{js,jvm}.Implicits._`. + +## Create an issue + +You can create an issue using `createIssue`, it takes as arguments: + +- the repository coordinates (owner and name of the repository) +- the content of the issue (title and body) +- other optional parameters: milestone id, labels and assignees which are only taken into account +if you have push access to the repository + +To create an issue: + +```tut:silent +val createIssue = + Github(accessToken).issues.createIssue("47deg", "github4s", "Github4s", "is awesome") + +createIssue.exec[cats.Id, HttpResponse[String]]() match { + case Left(e) => println("Something went wrong: s{e.getMessage}") + case Right(r) => println(r.result) +} +``` + +The `result` on the right is the created [Issue][issue-scala]. + +See [the API doc](https://developer.github.com/v3/issues/#create-an-issue) for full reference. + +## Edit an issue + +You can edit an existing issue using `editIssue`, it takes as arguments: + +- the repository coordinates (owner and name of the repository) +- the issue id +- the updated state of the issue (open or closed) +- the edited content of the issue (title and body) +- other optional parameters: milestone id, labels and assignees which are only taken into account +if you have push access to the repository + +To edit an issue: + +```tut:silent +val editIssue = + Github(accessToken).issues.editIssue("47deg", "github4s", 1, "open", "Github4s", "is still awesome") + +editIssue.exec[cats.Id, HttpResponse[String]]() match { + case Left(e) => println("Something went wrong: s{e.getMessage}") + case Right(r) => println(r.result) +} +``` + +the `result` on the right is the edited [Issue][issue-scala]. + +See [the API doc](https://developer.github.com/v3/issues/#edit-an-issue) for full reference. + +## List issues + +You can also list issues for a repository through `listIssues`, it take as arguments: + +- the repository coordinates (owner and name of the repository) + +To list the issues for a repository: + +```tut:silent +val listIssues = Github(accessToken).issues.listIssues("47deg", "github4s") + +listIssues.exec[cats.Id, HttpResponse[String]]() match { + case Left(e) => println("Something went wrong: s{e.getMessage}") + case Right(r) => println(r.result) +} +``` + +The `result` on the right is the corresponding [List[Issue]][issue-scala]. Note that it will +contain pull requests as Github considers pull requests as issues. + +See [the API doc](https://developer.github.com/v3/issues/#list-issues-for-a-repository) +for full reference. + +## Search issues + +Lastly, you can also search issues all across Github thanks to `searchIssues`, it takes as +arguments: + +- a query string (the URL encoding is taken care of by Github4s) +- a list of [SearchParam](https://github.com/47deg/github4s/blob/master/github4s/shared/src/main/scala/github4s/free/domain/SearchParam.scala) + +Let's say we want to search for the Scala bugs () which contain +the "existential" keyword in their title: + +```tut:silent +import github4s.free.domain._ +val searchParams = List( + OwnerParamInRepository("scala/bug"), + IssueTypeIssue, + SearchIn(Set(SearchInTitle)) +) +val searchIssues = Github(accessToken).issues.searchIssues("existential", searchParams) + +searchIssues.exec[cats.Id, HttpResponse[String]]() match { + case Left(e) => println("Something went wrong: s{e.getMessage}") + case Right(r) => println(r.result) +} +``` + +The `result` on the right is a [SearchIssuesResult][issue-scala]. + +See [the API doc](https://developer.github.com/v3/search/#search-issues) for full reference. + +[issue-scala]: https://github.com/47deg/github4s/blob/master/github4s/shared/src/main/scala/github4s/free/domain/Issue.scala \ No newline at end of file diff --git a/docs/src/main/tut/status.md b/docs/src/main/tut/status.md index 5e4fefd1c..8ec3be81a 100644 --- a/docs/src/main/tut/status.md +++ b/docs/src/main/tut/status.md @@ -27,7 +27,10 @@ val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN") ``` They also make use of `cats.Id` but any type container implementing `MonadError[M, Throwable]` will -do such as `cats.Eval` or `Future` (the only supported option for scala-js). +do. + +Support for `cats.Id`, `cats.Eval` and `Future` (the only supported option for scala-js) are +provided out of the box when importing `github4s.{js,jvm}.Implicits._`. ## Create a status @@ -38,21 +41,22 @@ You can create a status using `createStatus`, it takes as arguments: - the state of the status we want to create (can be pending, success, failure or error) - other optional parameters: target url, description and context -See [the API doc](https://developer.github.com/v3/repos/statuses/#parameters) for full reference. - To create a status: ```tut:silent -val createdStatus = +val createStatus = Github(accessToken).statuses.createStatus("47deg", "github4s", "aaaaaa", "pending") -createdStatus.exec[cats.Id, HttpResponse[String]]() match { +createStatus.exec[cats.Id, HttpResponse[String]]() match { case Left(e) => println("Something went wrong: s{e.getMessage}") case Right(r) => println(r.result) } ``` -The `result` on the right is the created [`Status`][status-scala]. +The `result` on the right is the created [Status][status-scala]. + +See [the API doc](https://developer.github.com/v3/repos/statuses/#create-a-status) for full +reference. ## List statuses @@ -73,7 +77,10 @@ listStatuses.exec[cats.Id, HttpResponse[String]]() match { } ``` -The `result` on the right is the corresponding [`List[Status]`][status-scala]. +The `result` on the right is the corresponding [List[Status]][status-scala]. + +See [the API doc](https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref) +for full reference. ## Get combined status @@ -90,7 +97,7 @@ combinedStatus.exec[cats.Id, HttpResponse[String]]() match { } ``` -The `result` on the right is a [`CombinedStatus`][status-scala]. +The `result` on the right is a [CombinedStatus][status-scala]. Note that the state of the combined status is the product of a heuristic detailed in [the API documentation](https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref).