зеркало из https://github.com/github/octobox.git
Setup API Docs generation and include in header dropdown
This commit is contained in:
jules2689
Родитель
d76bf25df1
Коммит
09edbe8f34
|
|
@ -23,4 +23,5 @@ config/initializers/custom.rb
|
|||
coverage
|
||||
.DS_Store
|
||||
public/assets
|
||||
public/docs
|
||||
.database
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
API Documentation
|
||||
---
|
||||
|
||||
This is the API Documentation for Octobox. With this API, you can access and manage your Github notifications and user profile.
|
||||
|
||||
## Authentication
|
||||
|
||||
Every user has an API Token that you can see on [your settings page](/settings). Octobox uses standard API Token-based authentication.
|
||||
|
||||
To use this authentication, simply send an Authentication header to Octobox:
|
||||
|
||||
```
|
||||
Authorization Bearer <token>
|
||||
```
|
||||
|
||||
For example, here is a basic Ruby example to get notifications:
|
||||
|
||||
```ruby
|
||||
require "net/http"
|
||||
require "uri"
|
||||
|
||||
base_url = "https://<url>"
|
||||
url = URI.parse("#{base_url}/notifications.json")
|
||||
|
||||
req = Net::HTTP::Get.new(url.path)
|
||||
req.add_field("Authorization", "Bearer #{token}")
|
||||
res = Net::HTTP.new(url.host, url.port).start do |http|
|
||||
http.request(req)
|
||||
end
|
||||
|
||||
puts res.body
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
The endpoints are listed by controller down the left hand side of these docs.
|
||||
|
||||
## Questions?
|
||||
|
||||
Please refer to the repository for this app. [You can find the repo here](https://github.com/octobox/octobox).
|
||||
|
|
@ -18,4 +18,6 @@ COPY Gemfile Gemfile.lock /usr/src/app/
|
|||
RUN bundle install --without test production --jobs 2
|
||||
|
||||
COPY . /usr/src/app
|
||||
# Generate API Docs
|
||||
RUN RAILS_ENV=development bin/rails api_docs:generate
|
||||
CMD ["bin/docker-start"]
|
||||
|
|
@ -24,6 +24,7 @@ in your GitHub settings for Octobox to work.
|
|||
* [Customizing Source Link for Modified Code](#customizing-source-link-for-modified-code)
|
||||
* [Adding a custom initializer](#adding-a-custom-initializer)
|
||||
* [Downloading subjects](#downloading-subjects)
|
||||
* [API Documentation](#api-documentation)
|
||||
|
||||
# Installation
|
||||
## Database Selection
|
||||
|
|
@ -285,6 +286,13 @@ To enable this feature set the following environment variable:
|
|||
|
||||
If you want this feature to work for private repositories, you'll need to [Customize the Scopes on GitHub](#customizing-the-scopes-on-github) adding `repo` scope to allow Octobox to get subject information for private issues and pull requests.
|
||||
|
||||
## API Documentation
|
||||
|
||||
API Documentation will be generated from the applications's controllers using `bin/rake api_docs:generate`. Once generated it will be automatically listed in the Header dropdown.
|
||||
|
||||
This is included by default in the container build using `Dockerfile`. To include in your build, simply run the command listed above before deploy.
|
||||
|
||||
|
||||
## Google Analytics
|
||||
|
||||
To enable Google analytics tracking set the following environment variable:
|
||||
|
|
|
|||
|
|
@ -6,13 +6,15 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Return a listing of notifications, including a summary of unread repos, notification reasons, and notification types
|
||||
#
|
||||
# :category: Notifications CRUD
|
||||
#
|
||||
# ==== Parameters
|
||||
#
|
||||
# * +:page+ - The page you would like to request
|
||||
# * +:per_page+ - The number of results you would like to return per page. Max 100, default 20.
|
||||
# * +:starred+ - Return only the user's starred notifications
|
||||
# * +:archive+ - Return only the user's archived notifications
|
||||
# * +:q: - Search by subject title of the notification
|
||||
# * +:q+ - Search by subject title of the notification
|
||||
#
|
||||
# ==== Notes
|
||||
#
|
||||
|
|
@ -20,50 +22,51 @@ class NotificationsController < ApplicationController
|
|||
#
|
||||
# ==== Example
|
||||
#
|
||||
# GET notifications.json
|
||||
# {
|
||||
# "pagination" : {
|
||||
# "total_notifications" : 1,
|
||||
# "page" : 1,
|
||||
# "total_pages" : 1,
|
||||
# "per_page" : 20
|
||||
# },
|
||||
# "types" : {
|
||||
# "PullRequest" : 1,
|
||||
# },
|
||||
# "reasons" : {
|
||||
# "mention" : 1
|
||||
# },
|
||||
# "unread_repositories" : {
|
||||
# "octobox/octobox" : 1
|
||||
# },
|
||||
# "notifications" : [
|
||||
# {
|
||||
# "id" : 29,
|
||||
# "github_id" : 320,
|
||||
# "reason" : "mention",
|
||||
# "unread" : true,
|
||||
# "archived" : false,
|
||||
# "starred" : false,
|
||||
# "url" : "https://api.github.com/notifications/threads/320",
|
||||
# "web_url" : "https://github.com/octobox/octobox/pull/320",
|
||||
# "last_read_at" : "2017-02-20 22:26:11 UTC",
|
||||
# "created_at" : "2017-02-22T15:49:33.750Z",
|
||||
# "updated_at" : "2017-02-22T15:40:21.000Z",
|
||||
# "subject":{
|
||||
# "title" : "Add JSON API",
|
||||
# "url" : "https://api.github.com/repos/octobox/octobox/pulls/320",
|
||||
# "type" : "PullRequest"
|
||||
# },
|
||||
# "repo":{
|
||||
# "id": 320,
|
||||
# "name" : "octobox/octobox",
|
||||
# "owner" : "octobox",
|
||||
# "repo_url" : "https://github.com/octobox/octobox"
|
||||
# }
|
||||
# }
|
||||
# ]
|
||||
# }
|
||||
# <code>GET notifications.json</code>
|
||||
#
|
||||
# {
|
||||
# "pagination" : {
|
||||
# "total_notifications" : 1,
|
||||
# "page" : 1,
|
||||
# "total_pages" : 1,
|
||||
# "per_page" : 20
|
||||
# },
|
||||
# "types" : {
|
||||
# "PullRequest" : 1,
|
||||
# },
|
||||
# "reasons" : {
|
||||
# "mention" : 1
|
||||
# },
|
||||
# "unread_repositories" : {
|
||||
# "octobox/octobox" : 1
|
||||
# },
|
||||
# "notifications" : [
|
||||
# {
|
||||
# "id" : 29,
|
||||
# "github_id" : 320,
|
||||
# "reason" : "mention",
|
||||
# "unread" : true,
|
||||
# "archived" : false,
|
||||
# "starred" : false,
|
||||
# "url" : "https://api.github.com/notifications/threads/320",
|
||||
# "web_url" : "https://github.com/octobox/octobox/pull/320",
|
||||
# "last_read_at" : "2017-02-20 22:26:11 UTC",
|
||||
# "created_at" : "2017-02-22T15:49:33.750Z",
|
||||
# "updated_at" : "2017-02-22T15:40:21.000Z",
|
||||
# "subject":{
|
||||
# "title" : "Add JSON API",
|
||||
# "url" : "https://api.github.com/repos/octobox/octobox/pulls/320",
|
||||
# "type" : "PullRequest"
|
||||
# },
|
||||
# "repo":{
|
||||
# "id": 320,
|
||||
# "name" : "octobox/octobox",
|
||||
# "owner" : "octobox",
|
||||
# "repo_url" : "https://github.com/octobox/octobox"
|
||||
# }
|
||||
# }
|
||||
# ]
|
||||
# }
|
||||
#
|
||||
def index
|
||||
scope = notifications_for_presentation
|
||||
|
|
@ -83,10 +86,12 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Return a count for the number of unread notifications
|
||||
#
|
||||
# :category: Notifications CRUD
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# GET notifications/unread_count.json
|
||||
# { "count" : 1 }
|
||||
# <code>GET notifications/unread_count.json</code>
|
||||
# { "count" : 1 }
|
||||
#
|
||||
def unread_count
|
||||
scope = current_user.notifications
|
||||
|
|
@ -96,14 +101,16 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Mute selected notifications, this will also archive them
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Parameters
|
||||
#
|
||||
# * +:id+ - An array of IDs of notifications you'd like to mute. If ID is 'all', all notifications will be muted
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/mute_selected.json?id=all
|
||||
# HEAD 204
|
||||
# <code>POST notifications/mute_selected.json?id=all</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def mute_selected
|
||||
Notification.mute(selected_notifications)
|
||||
|
|
@ -112,14 +119,16 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Archive selected notifications
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Parameters
|
||||
#
|
||||
# * +:id+ - An array of IDs of notifications you'd like to archive. If ID is 'all', all notifications will be archived
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/archive_selected.json?id=all
|
||||
# HEAD 204
|
||||
# <code>POST notifications/archive_selected.json?id=all</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def archive_selected
|
||||
selected_notifications.update_all(
|
||||
|
|
@ -130,14 +139,16 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Mark selected notifications as read
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Parameters
|
||||
#
|
||||
# * +:id+ - An array of IDs of notifications you'd like to mark as read. If ID is 'all', all notifications will be marked as read
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/mark_read_selected.json?id=all
|
||||
# HEAD 204
|
||||
# <code>POST notifications/mark_read_selected.json?id=all</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def mark_read_selected
|
||||
Notification.mark_read(selected_notifications)
|
||||
|
|
@ -146,10 +157,12 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Mark a notification as read
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/:id/mark_read.json
|
||||
# HEAD 204
|
||||
# <code>POST notifications/:id/mark_read.json</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def mark_read
|
||||
@notification.update_columns unread: false
|
||||
|
|
@ -158,10 +171,12 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Star a notification
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/:id/star.json
|
||||
# HEAD 204
|
||||
# <code>POST notifications/:id/star.json</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def star
|
||||
@notification.update_columns starred: !@notification.starred?
|
||||
|
|
@ -170,10 +185,12 @@ class NotificationsController < ApplicationController
|
|||
|
||||
# Synchronize notifications with GitHub
|
||||
#
|
||||
# :category: Notifications Actions
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# POST notifications/sync.json
|
||||
# HEAD 204
|
||||
# <code>POST notifications/sync.json</code>
|
||||
# HEAD 204
|
||||
#
|
||||
def sync
|
||||
current_user.sync_notifications
|
||||
|
|
|
|||
|
|
@ -6,20 +6,20 @@ class UsersController < ApplicationController
|
|||
#
|
||||
# ==== Example
|
||||
#
|
||||
# GET users/profile.json
|
||||
# {
|
||||
# "user" : {
|
||||
# "id" : 1,
|
||||
# "github_id" : 3074765,
|
||||
# "github_login" : "jules2689",
|
||||
# "last_synced_at" : "2017-02-22T15:49:32.104Z",
|
||||
# "created_at" : "2017-02-22T15:49:32.099Z",
|
||||
# "updated_at" : "2017-02-22T15:49:32.099Z"
|
||||
# }
|
||||
# }
|
||||
# <code>GET users/profile.json</code>
|
||||
# {
|
||||
# "user" : {
|
||||
# "id" : 1,
|
||||
# "github_id" : 3074765,
|
||||
# "github_login" : "jules2689",
|
||||
# "last_synced_at" : "2017-02-22T15:49:32.104Z",
|
||||
# "created_at" : "2017-02-22T15:49:32.099Z",
|
||||
# "updated_at" : "2017-02-22T15:49:32.099Z"
|
||||
# }
|
||||
# }
|
||||
def profile; end
|
||||
|
||||
def edit
|
||||
def edit # :nodoc:
|
||||
@latest_git_sha = Git.open(Rails.root).object('HEAD').sha[0..6] rescue nil
|
||||
end
|
||||
|
||||
|
|
@ -30,9 +30,10 @@ class UsersController < ApplicationController
|
|||
#
|
||||
# ==== Example
|
||||
#
|
||||
# PATCH users/:id.json
|
||||
# { "user" : { "refresh_interval" : 60000 } }
|
||||
# HEAD OK
|
||||
# <code>PATCH users/:id.json</code>
|
||||
# { "user" : { "refresh_interval" : 60000 } }
|
||||
#
|
||||
# HEAD OK
|
||||
#
|
||||
def update
|
||||
if current_user.update_attributes(update_user_params)
|
||||
|
|
@ -52,12 +53,12 @@ class UsersController < ApplicationController
|
|||
end
|
||||
end
|
||||
|
||||
# Delete your user profile. Only can delete the current user
|
||||
# Delete your user profile. Can only delete the current user
|
||||
#
|
||||
# ==== Example
|
||||
#
|
||||
# DELETE users/:id.json
|
||||
# HEAD OK
|
||||
# <code>DELETE users/:id.json</code>
|
||||
# HEAD OK
|
||||
#
|
||||
def destroy
|
||||
user = User.find(current_user.id)
|
||||
|
|
|
|||
|
|
@ -53,6 +53,14 @@
|
|||
Settings
|
||||
<% end %>
|
||||
</li>
|
||||
<% if File.exist?(Rails.root.join('public', 'docs', 'index.html')) %>
|
||||
<li>
|
||||
<%= link_to "docs/" do %>
|
||||
<%= octicon 'book', height: 16, class: 'text-muted' %>
|
||||
API Documentation
|
||||
<% end %>
|
||||
</li>
|
||||
<% end %>
|
||||
<li role="separator" class="divider"></li>
|
||||
<li>
|
||||
<%= link_to logout_path do %>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
require 'rdoc/task'
|
||||
|
||||
namespace :api_docs do
|
||||
RDoc::Task.new :generate do |rdoc|
|
||||
rdoc.main = "API_README.md"
|
||||
rdoc.rdoc_files.include(
|
||||
"app/controllers/notifications_controller.rb",
|
||||
"app/controllers/users_controller.rb",
|
||||
"API_README.md",
|
||||
)
|
||||
rdoc.rdoc_dir = "public/docs"
|
||||
rdoc.title = "Octobox API Documentation"
|
||||
end
|
||||
end
|
||||
Загрузка…
Ссылка в новой задаче