Verified Commit 74b97dc7 authored by Lukas Wiest's avatar Lukas Wiest 🚂
Browse files

docs: add GitHub to api/systems and uml diagram in dev-guide

parent 46ab087c
Pipeline #1705 passed with stages
in 1 minute and 25 seconds
# 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
// recommended option
GithubTicketSystem ts = (GithubTicketSystem) TicketSystem.fromUri("<uri>");
// second possible declaration
> gl = TicketSystem.fromUri("<uri>");
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://]<base url>::<owner>:<repo>[:<username>:<apikey>]
- 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
- implicit https authenticated, owner me, project hello-world, public gitlab
- explicit https authenticated, owner me, project hello-world, fictional github, non-standard port
### 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
GithubTicketSystem ts = TicketSystem.fromBuilder()
- implicit https authenticated, owner me, repo hello-world, public github
GithubTicketSystem ts = TicketSystem.fromBuilder()
.withAuthentication("me", "1234896102765abcddbda324bb3a3")
- explicit https authenticated, owner me, repo hello-world, fictional github, non-standard port
GithubTicketSystem ts = TicketSystem.fromBuilder()
.withAuthentication("me", "1234896102765abcddbda324bb3a3")
## 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"
GithubTicket = ts.createTicket()
.title("my new ticket")
Setting an assignee, has to be by user login name.
[core-ts]: ../../core/
# GitHub-Ticket
!!! todo
write usage api docs
......@@ -8,6 +8,10 @@ This is the full UML-diagram for the Unified-Ticketing library.
' ==========
' 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<GithubTicket>
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<Assignee>
+ body: String
+ labels: Set<Label>
+ number: int
+ state: String
+ title: String
# constructor()
class GithubTicketResponse.Assignee {
+ number: int
+ login: String
class GithubTicketResponse.Label {
+ name: String
class GithubTicketSystem {
- {static} logger: Logger
+ {static} fromUri(uri: String): GithubTicketSystem
__ instance definition __
# constructor()
+ createTicket(): GithubTicketBuilder
+ find(): GithubFilter
+ getTicketById(id: String): GithubTicket
+ hasAssigneeSupport(): boolean
+ hasDefaultPagination(): boolean
+ hasLabelSupport(): boolean
+ hasPaginationSupport(): boolean
+ hasReturnNullOnErrorSupport(): boolean
class GithubTicketSystemBuilder {
- {static} logger: Logger
__ instance definition __
# acceptHeader: String
# apiKey: String
# https: boolean
# owner: String
# repo: String
# username: String
+ constructor()
+ withAuthentication(username: String, apiKey: String): GithubTicketSystemBuilder
+ withHttp(): GithubTicketSystemBuilder
+ withHttps(): GithubTicketSystemBuilder
+ withOwner(owner: String): GithubTicketSystemBuilder
+ withRepo(repo: String): GithubTicketSystemBuilder
+ build(): GithubTicketSystem
' package connections
GithubFilter o-- GithubTicketSystem: "parent"
GithubTicketResponse o- GithubTicketResponse.Assignee: "inner class"
GithubTicketResponse o-down- GithubTicketResponse.Label: "inner class"
GithubTicketSystemBuilder --> GithubTicketSystem: "build()"
GithubTicketSystem --> GithubTicketBuilder: "createTicket()"
GithubTicketBuilder --> GithubTicket: "create()"
GithubTicketSystem *-- GithubTicketResponse
' core package connections
GithubFilter --|> Filter
GithubTicket --|> Ticket
GithubTicketAssignee --|> TicketAssignee
GithubTicketBuilder --|> TicketBuilder
GithubTicketSystem --|> TicketSystem
GithubTicketSystemBuilder --|> TicketSystemBuilder
RegisteredSystems --> GithubTicketSystemBuilder: "github()"
' ==========
' GitLab
' ==========
class GitlabFilter {
- {static} logger: Logger
......@@ -24,6 +24,9 @@ nav:
- Ticketsystem: 'api/core/'
- Exceptions: 'api/'
- Systems:
- GitHub:
- Ticket: 'api/systems/github/'
- Ticketsystem: 'api/systems/github/'
- GitLab:
- Ticket: 'api/systems/gitlab/'
- Ticketsystem: 'api/systems/gitlab/'
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment