Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

[WIP]: Add responses to documentation #25

Merged
merged 2 commits into from

3 participants

@henrikhodne
Owner

I started adding JSON responses to the documentation strings.

Do we want to do it this way, or do you think I should change something?

If you think this is a good way to do it, keep the pull request open and I'll add responses to the other endpoints too.

@joshk
Owner

@rkh your thoughts on this? we really need to improve the docs, I point people to the docs only to have little to show them.

@rkh
Owner

Seems good. Maybe we should send actual models through the API serializers?

@joshk
Owner

@henrikhodne can you rebase, and comment on this, and feel free to merge as well, we need to make some movement on this.

henrikhodne added some commits
@henrikhodne henrikhodne Add a way to add responses to documentation
You can add a predefined JSON response by entering
"json(:resource_name)" in the docstring. This will then be replaced
with the resource with the same name, found in
lib/travis/api/app/endpoint/documentation/resources.rb.
c1aaeee
@henrikhodne henrikhodne Add responses to repository endpoints 6f5f7d0
@henrikhodne
Owner

Rebased. I think I like the idea of running models through the API serializers, I'll look into doing that.

@henrikhodne henrikhodne merged commit a18f211 into from
@henrikhodne henrikhodne deleted the branch
@henrikhodne
Owner

After trying a few things, I decided not to use actual models. Since it'll run on production servers there were all kinds of issues with conflicting with actual entries in the database. This is a good start IMO.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 27, 2013
  1. @henrikhodne

    Add a way to add responses to documentation

    henrikhodne authored
    You can add a predefined JSON response by entering
    "json(:resource_name)" in the docstring. This will then be replaced
    with the resource with the same name, found in
    lib/travis/api/app/endpoint/documentation/resources.rb.
  2. @henrikhodne
This page is out of date. Refresh to see the latest.
View
2  lib/travis/api/app/endpoint/documentation.rb
@@ -1,4 +1,5 @@
require 'travis/api/app'
+require 'travis/api/app/endpoint/documentation/resources'
class Travis::Api::App
class Endpoint
@@ -44,6 +45,7 @@ def docs_for(entry)
def with_code_highlighting(str)
str.
+ gsub(/json\(:([^)]+)\)/) { "<pre>" + Resources::Helpers.json($1) + "</pre>" }.
gsub('<pre', '<pre class="prettyprint linenums pre-scrollable"').
gsub(/<\/?code>/, '').
gsub(/TODO:?/, '<span class="label label-warning">TODO</span>')
View
95 lib/travis/api/app/endpoint/documentation/resources.rb
@@ -0,0 +1,95 @@
+require 'json'
+
+class Travis::Api::App::Endpoint
+ module Resources
+ module Helpers
+ def self.json(key)
+ JSON.pretty_generate(Resources.const_get(key.to_s.upcase))
+ end
+ end
+
+ REPOSITORY_KEY = {
+ "public_key" => "-----BEGIN RSA PUBLIC KEY-----\nMIGJAoGBAOcx131amMqIzm5+FbZz+DhIgSDbFzjKKpzaN5UWVCrLSc57z64xxTV6\nkaOTZmjCWz6WpaPkFZY+czfL7lmuZ/Y6UNm0vupvdZ6t27SytFFGd1/RJlAe89tu\nGcIrC1vtEvQu2frMLvHqFylnGd5Gy64qkQT4KRhMsfZctX4z5VzTAgMBAAE=\n-----END RSA PUBLIC KEY-----\n",
+ }
+
+ REPOSITORY = {
+ "id" => 59,
+ "slug" => "travis-ci/travis-ci",
+ "description" => "A distributed build system for the open source community.",
+ "public_key" => REPOSITORY_KEY["public_key"],
+ "last_build_id" => 3373911,
+ "last_build_number" => "2188",
+ "last_build_status" => 0,
+ "last_build_result" => 0,
+ "last_build_duration" => 221,
+ "last_build_language" => nil,
+ "last_build_started_at" => "2012-11-27T01:01:28Z",
+ "last_build_finished_at" => "2012-11-27T01:05:09Z",
+ }
+
+ REPOSITORIES = [REPOSITORY]
+
+ SHORT_BUILD = {
+ "id" => 3373911,
+ "repository_id" => 59,
+ "number" => "2188",
+ "state" => "finished",
+ "result" => 0,
+ "started_at" => "2012-11-27T01:01:28Z",
+ "finished_at" => "2012-11-27T01:05:09Z",
+ "duration" => 221,
+ "commit" => "a0e4dada7eb30b41817d9d3c5222b519502ef87a",
+ "branch" => "master",
+ "message" => "no need to set up services",
+ "event_type" => "push",
+ }
+
+ BUILDS = [
+ SHORT_BUILD,
+ ]
+
+ CONFIG = {
+ "language" => "ruby",
+ "rvm" => [
+ "1.9.3",
+ ],
+ "bundler_args" => "--without development",
+ "before_install" => [
+ "gem install bundler --pre",
+ ],
+ "before_script" => [
+ "cp config/database.example.yml config/database.yml"
+ ],
+ "script" => "RAILS_ENV=test bundle exec rake test:ci --trace",
+ "notifications" => {
+ "irc" => "irc.freenode.org#travis",
+ "campfire" => {
+ "secure" => "JJezWGD9KJY/LC2aznI3Zyohy31VTIhcTKX7RWR4C/C8YKbW9kZv3xV6Vn11\nSHxJTeZo6st2Bpv6tjlWZ+HCR09kyCNavIChedla3+oHOiuL0D4gSo+gkTNW\nUKYZz9mcQUd9RoQpTeyxvdvX+l7z62/7JwFA7txHOqxbTS8jrjc="
+ }
+ },
+ ".result" => "configured"
+ }
+
+ BUILD = SHORT_BUILD.merge({
+ "config" => CONFIG,
+ "committed_at" => "2012-11-27T01:01:06Z",
+ "author_name" => "Sven Fuchs",
+ "author_email" => "me@svenfuchs.com",
+ "committer_name" => "Sven Fuchs",
+ "committer_email" => "me@svenfuchs.com",
+ "compare_url" => "https://github.com/travis-ci/travis-ci/compare/18b6874865f2...a0e4dada7eb3",
+ "matrix" => [
+ {
+ "id" => 3373912,
+ "repository_id" => 59,
+ "number" => "2188.1",
+ "config" => CONFIG,
+ "result" => 0,
+ "started_at" => "2012-11-27T01:01:28Z",
+ "finished_at" => "2012-11-27T01:05:09Z",
+ "allow_failure" => false
+ }
+ ]
+ })
+ end
+end
View
42 lib/travis/api/app/endpoint/repos.rb
@@ -8,10 +8,19 @@ class Repos < Endpoint
# You can filter the repositories by adding parameters to the request. For example, you can get all repositories
# owned by johndoe by adding `owner_name=johndoe`, or all repositories that johndoe has access to by adding
# `member=johndoe`. The parameter names correspond to the keys of the response hash.
+ #
+ # ### Response
+ #
+ # json(:repositories)
get '/' do
respond_with service(:find_repos, params)
end
+ # Gets the repository with the given id.
+ #
+ # ### Response
+ #
+ # json(:repository)
get '/:id' do
respond_with service(:find_repo, params)
end
@@ -20,6 +29,15 @@ class Repos < Endpoint
respond_with service(:find_repo, params.merge(schema: 'cc'))
end
+ # Get the public key for the repository with the given id.
+ #
+ # This can be used to encrypt secure variables in the build configuration. See
+ # [the encryption keys](http://about.travis-ci.org/docs/user/encryption-keys/) documentation page for more
+ # information.
+ #
+ # ### Response
+ #
+ # json(:repository_key)
get '/:id/key' do
respond_with service(:find_repo_key, params), version: :v2
end
@@ -28,14 +46,29 @@ class Repos < Endpoint
respond_with service(:regenerate_repo_key, params), version: :v2
end
+ # Gets the repository with the given name.
+ #
+ # ### Response
+ #
+ # json(:repository)
get '/:owner_name/:name' do
respond_with service(:find_repo, params)
end
+ # Gets the builds for the repository with the given name.
+ #
+ # ### Response
+ #
+ # json(:builds)
get '/:owner_name/:name/builds' do
respond_with service(:find_builds, params)
end
+ # Get a build with the given id in the repository with the given name.
+ #
+ # ### Response
+ #
+ # json(:build)
get '/:owner_name/:name/builds/:id' do
respond_with service(:find_build, params)
end
@@ -44,6 +77,15 @@ class Repos < Endpoint
respond_with service(:find_repo, params.merge(schema: 'cc'))
end
+ # Get the public key for a given repository.
+ #
+ # This can be used to encrypt secure variables in the build configuration. See
+ # [the encryption keys](http://about.travis-ci.org/docs/user/encryption-keys/) documentation page for more
+ # information.
+ #
+ # ### Response
+ #
+ # json(:repository_key)
get '/:owner_name/:name/key' do
respond_with service(:find_repo_key, params), version: :v2
end
Something went wrong with that request. Please try again.