diff --git a/docs/api/systems/github/ticket-system.md b/docs/api/systems/github/ticket-system.md new file mode 100644 index 0000000000000000000000000000000000000000..0723394fc55187f107833944b95fd9525d242a0c --- /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 0000000000000000000000000000000000000000..cb4e6c2101ee1667c4f6bbd65fd7d17824a70de8 --- /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 c3666ae1af6d479a067cea973f12e996739251ce..1983435e39387f1846bb98175a2414818c721b22 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