From 4015710b1811b8283842afa535d4a83785d5c245 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 21 Dec 2020 13:36:09 +0100 Subject: [PATCH 1/3] chore(docs/index): change badge color for latest tag to 'success' --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 14ae6b6..07fe330 100644 --- a/docs/index.md +++ b/docs/index.md @@ -64,7 +64,7 @@ He is the current maintainer for this project and the appropriate contact for qu [badge-conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg [badge-gplv3]: https://img.shields.io/badge/License-GPLv3-blue.svg [badge-latest-pipe]: https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1 -[badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=green&label=maven&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 +[badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=success&label=maven&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 [badge-master-pipe]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg [convcomm]: https://conventionalcommits.org [gplv3]: unified-ticketing/license-softlink.md -- GitLab From 46ab087c31e930938caf0835afd2d54eef6ddae5 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 21 Dec 2020 14:54:23 +0100 Subject: [PATCH 2/3] refactor(docs/uml): make GitlabTicketResponse inner class name unique --- docs/developers-guide/uml.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers-guide/uml.md b/docs/developers-guide/uml.md index c3666ae..3f406b7 100644 --- a/docs/developers-guide/uml.md +++ b/docs/developers-guide/uml.md @@ -346,7 +346,7 @@ class GitlabTicketResponse { # constructor() } -class Assignee { +class GitlabTicketResponse.Assignee { + id: int + name: String + username: String @@ -392,7 +392,7 @@ class GitlabTicketSystemBuilder { ' package connections GitlabFilter o-- GitlabTicketSystem: "parent" -GitlabTicketResponse o- Assignee: "inner class" +GitlabTicketResponse o- GitlabTicketResponse.Assignee: "inner class" GitlabTicketSystemBuilder --> GitlabTicketSystem: "build()" GitlabTicketSystem --> GitlabTicketBuilder: "createTicket()" GitlabTicketBuilder --> GitlabTicket: "create()" -- GitLab From 74b97dc7b1b01eb89b59bd4669793e36d2265f3f Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 21 Dec 2020 14:56:56 +0100 Subject: [PATCH 3/3] docs: add GitHub to api/systems and uml diagram in dev-guide --- docs/api/systems/github/ticket-system.md | 140 +++++++++++++++++++++++ docs/api/systems/github/ticket.md | 4 + docs/developers-guide/uml.md | 134 ++++++++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 281 insertions(+) create mode 100644 docs/api/systems/github/ticket-system.md create mode 100644 docs/api/systems/github/ticket.md diff --git a/docs/api/systems/github/ticket-system.md b/docs/api/systems/github/ticket-system.md new file mode 100644 index 0000000..0723394 --- /dev/null +++ b/docs/api/systems/github/ticket-system.md @@ -0,0 +1,140 @@ +# GitHub-Ticketsystem + +This documents GitHub specific things for the integration to this library. +For the global parts, see in the [core sections Ticketsystem site][core-ts]. + +## create new instance + +A `GithubTicketSystem` object is always referencing a specific GitHub project. +Mandatory information to instantiate it, are the GitHub instances base url, the project owner and project. + +For public accessible actions, it can be used anonymously. +Other operations have to be authenticated using an username and a personal access token. + +For all calls the `accept` header will be set to `application/vnd.github.v3+json`. +If not configured otherwise, connections will use `https`. + +### by URI + +```java +// recommended option +GithubTicketSystem ts = (GithubTicketSystem) TicketSystem.fromUri(""); + +// second possible declaration +TicketSystem< + GithubTicket, + GithubTicketSystem, + GithubTicketBuilder, + GithubFilter + > gl = TicketSystem.fromUri(""); +``` + +The first declaration option uses the child-class from the GitHub implementation directly. +The second option uses the parent-class instead, +defining the different implementations with Generics. + +Use the first option, if you're sure you want to use GitHub no matter what. +This way you can see GitHub specific methods, +whereas the second option keeps you limited on the global defined ones. +If you may switch ticket systems in the future, +the second option forces you to not use system specific stuff, making a transition easier. + +The URI to pass has to match this format: +``` +unifiedticketing:github:[http://|https://]:::[::] +``` + +- protocol for http/https is optional. If not given, https is used +- base url can contain also non-standard port hosted github instances +- username and api key if authentication needed, otherwise anonymous access is used + +??? example "URI examples" + - non-https anonymous, owner me, project hello-world, public gitlab + `unifiedticketing:github:http://api.github.com::me:hello-world` + - implicit https authenticated, owner me, project hello-world, public gitlab + `unifiedticketing:github:api.github.com::me:hello-world:me:1234896102765abcddbda324bb3a3` + - explicit https authenticated, owner me, project hello-world, fictional github, non-standard port + `unifiedticketing:github:https://api.github.example.org:8080::me:hello-world:me:1234896102765abcddbda324bb3a3` + +### by builder + +For instantiation from the builder, +mostly the same like building by URI applies. + +!!! warning + Passing the base url ensure the protocol (http or https) is removed + +??? example "builder examples" + - non-https anonymous, owner me, repo hello-world, public github + ```java + GithubTicketSystem ts = TicketSystem.fromBuilder() + .github() + .withBaseUrl("api.github.com") + .withHttp() + .withOwner("me") + .withRepo("hello-world") + .build(); + ``` + - implicit https authenticated, owner me, repo hello-world, public github + ```java + GithubTicketSystem ts = TicketSystem.fromBuilder() + .github() + .withBaseUrl("api.github.com") + .withOwner("me") + .withRepo("hello-world") + .withAuthentication("me", "1234896102765abcddbda324bb3a3") + .build(); + ``` + - explicit https authenticated, owner me, repo hello-world, fictional github, non-standard port + ```java + GithubTicketSystem ts = TicketSystem.fromBuilder() + .github() + .withBaseUrl("api.github.example.org:8080") + .withHttps() + .withOwner("me") + .withRepo("hello-world") + .withAuthentication("me", "1234896102765abcddbda324bb3a3") + .build(); + ``` + +## list tickets + +!!! warning "default pagination" + GitHub has a default pagination on _30_ elements per page. + Highest possible value is _100_ elements. [[Link]][api-docs-pagination] + +!!! info "assignees" + GitHub implementation supports the fields `id` and `username`. + If ticket has no assignees, assignee field stays `null`. + +From the filters shown on the global `TicketSystem` docs, +the ones for title, description filter and ticket id's are not natively supported by the GitHub API. +If such a filter is used, +this get's done locally after receiving the response from GitHub, +before handing it to the user. + +## get single ticket + +As the GitHub API doesn't support a ticket-id filter on the list endpoint, +the method for getting a single ticket by it's id uses the single ticket endpoint. + +If you use the Filter class with a single ticket id as only filter, +you end up fetching all tickets of that repo, filtering out all non matching ones locally. + +## create new ticket + +For a new GitHub ticket a title is mandatory. +Everything else is optional. + +!!! example "minimal example" + ```java + GithubTicket = ts.createTicket() + .title("my new ticket") + .create(); + ``` + +Setting an assignee, has to be by user login name. + +[core-ts]: ../../core/ticket-system.md +[api-docs-issues-list]: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues#list-repository-issues +[api-docs-pagination]: https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#pagination diff --git a/docs/api/systems/github/ticket.md b/docs/api/systems/github/ticket.md new file mode 100644 index 0000000..cb4e6c2 --- /dev/null +++ b/docs/api/systems/github/ticket.md @@ -0,0 +1,4 @@ +# GitHub-Ticket + +!!! todo + write usage api docs diff --git a/docs/developers-guide/uml.md b/docs/developers-guide/uml.md index 3f406b7..1983435 100644 --- a/docs/developers-guide/uml.md +++ b/docs/developers-guide/uml.md @@ -8,6 +8,10 @@ This is the full UML-diagram for the Unified-Ticketing library. ```plantuml +' ========== +' Core +' ========== + abstract Filter { __ generics definition __ T extends Ticket @@ -235,6 +239,10 @@ Ticket o-- TicketAssignee TicketSystem --> TicketBuilder: "createTicket()" TicketBuilder --> Ticket: "create()" +' ========== +' Exceptions +' ========== + class AssertionException { + constructor() + constructor(msg: String) @@ -291,6 +299,132 @@ HttpResponseException -[hidden]down- SerializationException SerializationException -[hidden]down- UnifiedticketingException UnifiedticketingException -[hidden]down- UnsupportedFunctionException +' ========== +' GitHub +' ========== + +class GithubFilter { + - {static} logger: Logger + + __ instance definition __ + # parent: GithubTicketSystem + + # getHttpClient(): OkHttpClient + + get(): List +} + +class GithubTicket { + - {static} logger: Logger + + # {static} fromTicketResponse(\n\tparent: GithubTicketSystem,\n\tresponse: GithubTicketResponse\n): GithubTicket + + __ instance definition __ + # constructor(parent: GithubTicketSystem) + + + addAssignee(userId: String): GithubTicket + + removeAssignee(userId: String): GithubTicket + + save(): GithubTicket + + + deepEquals(o: Object): boolean +} + +class GithubTicketAssignee { + # constructor(id: int, username: String) +} + +class GithubTicketBuilder { + - {static} logger: Logger + + __ instant definition __ + # constructor(parent: GithubTicketSystem) + + # getHttpClient(): OkHttpClient + + create(): GitlabTicket +} + +class GithubTicketResponse { + + assignees: Set + + body: String + + labels: Set