[RFC] Using Swagger to define REST API for Gerrit?
283 views
Skip to first unread message
Kenny Ho
Dec 1, 2016, 5:19:05 PM12/1/16
to Repo and Gerrit Discussion
Swagger - http://swagger.io/
From their website:
"Swagger Specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.
From their website:
"Swagger Specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.
The specification is the basis of the OpenAPI Specification (OAS) and is developed in an open, transparent, and collaborative community to standardize the way RESTful interfaces are defined."
Pros:
- Richer documentation (automatic generation)
- Code gen (both server side and client side. get something like https://pypi.python.org/pypi/gerritlib for many other languages automatically)
Notable users:
http://apievangelist.com/2015/03/30/quantifying-the-community-around-the-swagger-api-specification/
Do you think adopting this for Gerrit would be useful?
To get a taste of what it will be, I have converted small part of the API to swagger. You can visit http://editor.swagger.io/ and paste/replace the following in the left panel of the site:
# this is an example of the Gerrit API in Swagger spec
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
title: Gerrit Code Review API
description: Gerrit Code Review comes with a REST like API available over HTTP. The API is suitable for automated tools to build upon, as well as supporting some ad-hoc scripting use cases
version: "2.13.3"
# the domain of the service
host: gerrit.acme.com
# array of all schemes that your API supports
schemes:
- https
- http
# will be prefixed to all paths
#basePath: /v1
produces:
- application/json
paths:
/changes:
post:
summary: Create a new Change
description: The change input ChangeInput entity must be provided in the request body.
parameters:
- name: input
in: body
required: true
schema:
$ref: "#/definitions/ChangeInput"
responses:
200:
description: A ChangeInfo entity is returned that describes the resulting change.
schema:
$ref: "#/definitions/ChangeInfo"
get:
summary: Changes
description: |
Queries changes visible to the caller. The n parameter can be used . As result a list of [ChangeInfo](https://gerrit-documentation.storage.googleapis.com/Documentation/2.13.3/rest-api-changes.html#change-info) entries is returned. The change output is sorted by the last update time, most recently updated to oldest updated.
If the number of changes matching the query exceeds either the internal limit or a supplied n query parameter, the last change object has a _more_changes: true JSON field set.
parameters:
- name: q
in: query
description: |
[query string](https://gerrit-documentation.storage.googleapis.com/Documentation/2.13.3/user-search.html#_search_operators)
required: true
type: string
- name: n
in: query
description: To limit the returned results
required: false
type: number
format: integer
- name: S
in: query
description: Skip a number of changes from the list
required: false
type: number
format: integer
tags:
- Changes
responses:
200:
description: An array of ChangeInfo
schema:
type: array
items:
$ref: '#/definitions/ChangeInfo'
# default:
# description: Unexpected error
# schema:
# $ref: '#/definitions/Error'
definitions:
ChangeInfo:
type: object
required:
- id
- project
- branch
- change_id
- subject
- status
- created
- updated
- insertions
- deletions
- _number
- owner
- reviewers
properties:
id:
type: string
description: 'The ID of the change in the format "''<project>~<branch>~<Change-Id>''", where ''project'', ''branch'' and ''Change-Id'' are URL encoded. For ''branch'' the refs/heads/ prefix is omitted.'
project:
type: string
description: The name of the project.
branch:
type: string
description: "The name of the target branch.\nThe refs/heads/ prefix is omitted."
topic:
type: string
description: The topic to which this change belongs.
change_id:
type: string
description: The Change-Id of the change.
subject:
type: string
description: The subject of the change (header line of the commit message).
status:
type: string
description: The status of the change (NEW, MERGED, ABANDONED, DRAFT).
created:
type: string
description: The timestamp of when the change was created.
updated:
type: string
description: The timestamp of when the change was last updated.
submitted:
type: boolean
description: The timestamp of when the change was submitted. Only set for merged changes
starred:
type: string
description: Whether the calling user has starred this change with the default label.
stars:
type: string
description: A list of star labels that are applied by the calling user to this change. The labels are lexicographically sorted.
reviewed:
type: boolean
description: Whether the change was reviewed by the calling user. Only set if reviewed is requested. Not set if false
submit_type:
type: string
description: "The submit type of the change.\nNot set for merged changes."
mergeable:
type: string
description: "Whether the change is mergeable.\nNot set for merged changes, or if the change has not yet been tested."
insertions:
type: string
description: Number of inserted lines.
deletions:
type: string
description: Number of deleted lines.
_number:
type: string
description: The legacy numeric ID of the change.
owner: #issue of ignored description https://github.com/OAI/OpenAPI-Specification/issues/556
$ref: '#/definitions/AccountInfo'
description: The owner of the change as an AccountInfo entity.
actions:
type: string
description: Actions the caller might be able to perform on this revision. The information is a map of view name to ActionInfo entities.
labels:
type: string
description: "The labels of the change as a map that maps the label names to LabelInfo entries.\nOnly set if labels or detailed labels are requested."
permitted_labels:
type: string
description: "A map of the permitted labels that maps a label name to the list of values that are allowed for that label.\nOnly set if detailed labels are requested."
removable_reviewers:
description: "The reviewers that can be removed by the calling user as a list of AccountInfo entities.\nOnly set if detailed labels are requested."
type: array
items:
$ref: '#/definitions/AccountInfo'
reviewers:
description: "The reviewers as a map that maps a reviewer state to a list of AccountInfo entities. Possible reviewer states are REVIEWER, CC and REMOVED.\nREVIEWER: Users with at least one non-zero vote on the change.\nCC: Users that were added to the change, but have not voted.\nREMOVED: Users that were previously reviewers on the change, but have been removed.\nOnly set if detailed labels are requested."
type: array
items:
$ref: '#/definitions/AccountInfo'
reviewer_updates:
$ref: "#/definitions/ReviewerUpdateInfo"
description: Updates to reviewers set for the change as ReviewerUpdateInfo entities. Only set if reviewer updates are requested and if NoteDb is enabled.
messages:
type: string
description: "Messages associated with the change as a list of ChangeMessageInfo entities.\nOnly set if messages are requested."
current_revision:
type: string
description: "The commit ID of the current patch set of this change.\nOnly set if the current revision is requested or if all revisions are requested."
revisions:
type: string
description: "All patch sets of this change as a map that maps the commit ID of the patch set to a RevisionInfo entity.\nOnly set if the current revision is requested (in which case it will only contain a key for the current revision) or if all revisions are requested."
_more_changes:
type: boolean
description: "Whether the query would deliver more results if not limited.\nOnly set on the last change that is returned. Not set if false"
problems:
description: A list of ProblemInfo entities describing potential problems with this change. Only set if CHECK is set.
type: array
items:
$ref: '#/definitions/ProblemInfo'
ProblemInfo:
description: contains a description of a potential consistency problem with a change. These are not related to the code review process, but rather indicate some inconsistency in Gerrit’s database or repository metadata related to the enclosing change.
type: object
required:
- message
properties:
message:
type: string
description: Plaintext message describing the problem with the change.
status:
type: string
description: The status of fixing the problem (FIXED, FIX_FAILED). Only set if a fix was attempted.
outcome:
type: string
description: If status is set, an additional plaintext message describing the outcome of the fix.
ReviewerUpdateInfo:
description: The ReviewerUpdateInfo entity contains information about updates to change’s reviewers set.
type: object
required:
- updated
- updated_by
- reviewer
- state
properties:
updated:
type: string
description: Timestamp of the update.
updated_by:
$ref: '#/definitions/AccountInfo'
reviewer:
$ref: '#/definitions/AccountInfo'
state:
type: string
description: The reviewer state, one of REVIEWER, CC or REMOVED.
AccountInfo:
type: object
required:
- _account_id
properties:
_account_id:
type: string
description: The numeric ID of the account.
name:
type: string
description: The full name of the user. Only set if detailed account information is requested. See option DETAILED_ACCOUNTS for change queries and option DETAILS for account queries.
email:
type: string
description: The email address the user prefers to be contacted through. Only set if detailed account information is requested. See option DETAILED_ACCOUNTS for change queries and options DETAILS and ALL_EMAILS for account queries.
secondary_emails:
description: A list of the secondary email addresses of the user. Only set for account queries when the ALL_EMAILS option is set.
type: array
items:
type: string
username:
type: string
description: The username of the user. Only set if detailed account information is requested. See option DETAILED_ACCOUNTS for change queries and option DETAILS for account queries.
_more_account:
type: boolean
description: Whether the query would deliver more results if not limited. Only set on the last account that is returned.
ChangeInput:
type: object
required:
- project
- branch
- subject
properties:
project:
type: string
description: The name of the project.
branch:
type: string
description: The name of the target branch. The refs/heads/ prefix is omitted.
subject:
type: string
description: The subject of the change (header line of the commit message).
topic:
type: string
description: The topic to which this change belongs.
status:
type: string
description: The topic to which this change belongs.
base_change:
type: string
description: A {change-id} that identifies the base change for a create change operation.
new_branch:
type: boolean
description: Allow creating a new branch when set to true. (Default to false.)
merge:
type: string
description: The detail of a merge commit as a MergeInput entity.
ery...@gmail.com
Dec 2, 2016, 6:35:26 PM12/2/16
to Repo and Gerrit Discussion
I think adopting swagger is a good idea. At CollabNet we use it for documenting our internal Gerrit API that is used by TeamForge code browser. See [1] (slide 13). Swagger not only provides easy way for automated documentation but the code generation feature you mention is really cool. From [2]:
Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.
So +1 for Swagger adoption. I also look forward to versioned Gerrit REST API so that our internal API become obsolete.
Best regards,
Eryk Szymanski
On Thursday, December 1, 2016 at 11:19:05 PM UTC+1, Kenny Ho wrote:
Swagger - http://swagger.io/
From their website:
"Swagger Specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.The specification is the basis of the OpenAPI Specification (OAS) and is developed in an open, transparent, and collaborative community to standardize the way RESTful interfaces are defined."
Pros:
- Richer documentation (automatic generation)
- Code gen (both server side and client side. get something like https://pypi.python.org/pypi/gerritlib for many other languages automatically)
Notable users:
http://apievangelist.com/2015/03/30/quantifying-the-community-around-the-swagger-api-specification/
Do you think adopting this for Gerrit would be useful?
To get a taste of what it will be, I have converted small part of the API to swagger. You can visit http://editor.swagger.io/ and paste/replace the following in the left panel of the site:
[...]
lucamilanesio
Dec 5, 2019, 5:58:16 AM12/5/19
to Repo and Gerrit Discussion
I know it is an old thread ... however, it came back during the integration with the checks plugin REST-API.
On Friday, December 2, 2016 at 11:35:26 PM UTC, ery...@gmail.com wrote:
I think adopting swagger is a good idea. At CollabNet we use it for documenting our internal Gerrit API that is used by TeamForge code browser. See [1] (slide 13). Swagger not only provides easy way for automated documentation but the code generation feature you mention is really cool. From [2]:Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.So +1 for Swagger adoption. I also look forward to versioned Gerrit REST API so that our internal API become obsolete.
+1 from my side also.
It would allow Gerrit API to become more popular and integrated with many more languages.
Any other opinion?
Luca.
Edwin Kempin
Dec 5, 2019, 6:00:31 AM12/5/19
to lucamilanesio, Repo and Gerrit Discussion
We have an issue for this:
Let's continue this discussion there.
--Luca.
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en
---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/9d06cce7-4af6-4ca6-b634-01b419cc1f36%40googlegroups.com.
lucamilanesio
Dec 5, 2019, 6:03:13 AM12/5/19
to Repo and Gerrit Discussion
On Thursday, December 5, 2019 at 11:00:31 AM UTC, Edwin Kempin wrote:
On Thu, Dec 5, 2019 at 11:58 AM lucamilanesio <luca.m...@gmail.com> wrote:I know it is an old thread ... however, it came back during the integration with the checks plugin REST-API.
On Friday, December 2, 2016 at 11:35:26 PM UTC, ery...@gmail.com wrote:I think adopting swagger is a good idea. At CollabNet we use it for documenting our internal Gerrit API that is used by TeamForge code browser. See [1] (slide 13). Swagger not only provides easy way for automated documentation but the code generation feature you mention is really cool. From [2]:Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.So +1 for Swagger adoption. I also look forward to versioned Gerrit REST API so that our internal API become obsolete.+1 from my side also.It would allow Gerrit API to become more popular and integrated with many more languages.Any other opinion?We have an issue for this:Let's continue this discussion there.
Cool, created a backlink to this historic discussion.
Luca.
More info at http://groups.google.com/group/repo-discuss?hl=en
---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-d...@googlegroups.com.
Reply all
Reply to author
Forward
0 new messages