Fixes PLAT-3550
Test Plan:
- Verify there is no 'API Token Scopes' under OAuth2
- Verify there is only one link 'API Token Scopes' under Resources
- Verify there is no code left related to generating the 'API Token
Scopes' table under OAuth2
Change-Id: Ib00a4aeec102eafc22169ac5322b581fef797a0b
Reviewed-on: https://gerrit.instructure.com/155247
Tested-by: Jenkins
Reviewed-by: Weston Dransfield <wdransfield@instructure.com>
QA-Review: Weston Dransfield <wdransfield@instructure.com>
Product-Review: Jesse Poulos <jpoulos@instructure.com>
Closes PLAT-3394
Test Plan:
- Run the `doc:api` rake task
- Navigate to /doc/api/index.html and verify there
are two new links in the OAuth2 section ("Developer
Keys" and "API Token Scopes")
- Verify both links work
- Verify the token scopes documentation has a table
for each scope group and includes all Canvas
scopes
- Verify "Resources" documentation pages now display
the scope along with each API endpoint
Change-Id: I2fea0ff531744dbaf63d24619b3c0e9655a25a7a
Reviewed-on: https://gerrit.instructure.com/151010
QA-Review: August Thornton <august@instructure.com>
Reviewed-by: Nathan Mills <nathanm@instructure.com>
Tested-by: Jenkins
Product-Review: Jesse Poulos <jpoulos@instructure.com>
fixes CNVS-34845
in particular, delete a file (lib/kaltura.rb) that is never used anymore,
and move api_routes.rb out of lib, as it's not meant to ever be loaded
in the app
Change-Id: Ia950b3eb50b90dfaccec1784e3e612589091989e
Reviewed-on: https://gerrit.instructure.com/105444
Tested-by: Jenkins
Reviewed-by: Simon Williams <simon@instructure.com>
Product-Review: Cody Cutrer <cody@instructure.com>
QA-Review: Cody Cutrer <cody@instructure.com>
Add docs on how to update them
Update everytime we run doc:api
Change-Id: I3c7aa55d051fa5474e267897138ab01c3c7c3fb8
Reviewed-on: https://gerrit.instructure.com/102177
Reviewed-by: Jesse Poulos <jpoulos@instructure.com>
Reviewed-by: Nathan Mills <nathanm@instructure.com>
QA-Review: August Thornton <august@instructure.com>
Tested-by: Jenkins
Product-Review: Brad Horrocks <bhorrocks@instructure.com>
fixes CNVS-15130
allows access to a plugin's models (during truncation for specs),
migrations, assets, periodic jobs, prepended routes, api routes (during
documentation), flagging as reloadable, spec docs, etc. once the plugin
lives in gems/plugins/ instead of vendor/plugins/
Change-Id: Ia7a2fdf5ad6258c5de962e982b6bf62ebaf4d075
Reviewed-on: https://gerrit.instructure.com/42287
Reviewed-by: Rob Orton <rob@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>
QA-Review: August Thornton <august@instructure.com>
Product-Review: Jacob Fugal <jacob@instructure.com>
Closes CNVS-12019
Test plan:
- generate the API docs using `bundle exec rake doc:api`
- verify that all the quiz APIs are included in the docs
- verify that the appendices are functional (in the QuizSubmissions
API for example)
Change-Id: I80c6a10c13777d0b88fe96a8114f25b9a2a6f007
Reviewed-on: https://gerrit.instructure.com/32490
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Derek DeVries <ddevries@instructure.com>
QA-Review: Myller de Araujo <myller@instructure.com>
Product-Review: Derek DeVries <ddevries@instructure.com>
- Explicitly describe path parameters (e.g. "id", "account_id") so
that swagger will autogenerate the correct code.
- Use :resources which is already grouped, rather than :object, which
is not.
- Guess type information from current sample @object models
- Accept @model in API docs as a better alternative to @object.
@model descriptions use the JSON-schema draft 4 specification,
which is what Swagger uses.
See https://github.com/wordnik/swagger-core/wiki/Datatypes
- Add some swagger json generator specs
- Fix SubmissionsController's "Submission" object
Change-Id: I71befe1d2cea039fd996124e7de9cab2e639e191
Reviewed-on: https://gerrit.instructure.com/23831
Reviewed-by: Brian Palmer <brianp@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>
Product-Review: Duane Johnson <duane@instructure.com>
QA-Review: Duane Johnson <duane@instructure.com>
Add 'swagger' API metadata generator from Yard. This metadata
can be used to generate a Canvas API wrapper library, or to benefit
from the swagger doc ecosystem.
See https://github.com/wordnik/swagger-core/wiki
Test Plan:
- Call 'rake doc:api API_YML=1' from the command line
- Check that api.yml file is created in current directory
fixes CNVS-7311
Change-Id: I9c5f756192794e5ea767c4db745a777cd63c3942
Reviewed-on: https://gerrit.instructure.com/23079
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Nathan Mills <nathanm@instructure.com>
Product-Review: Duane Johnson <duane@instructure.com>
QA-Review: Duane Johnson <duane@instructure.com>
Useful things the commit brings:
1. Source documentation can now include images and out-of-source examples
2. Source documentation can now be supplemented by "appendixes" for
documenting advanced or uncommon usage, auxiliary examples, or any
supplementary content
3. An implementation of the YARD @see tag that utilizes the canvas
YARD linkify helper
Necessary changes for integration were:
* Gemfile now includes 'yard-appendix'
* Rake task for generating API docs (doc:api) made more readable and
now supports asset migration (images and examples)
* Canvas YARD 'api' template now handles :appendix sections provided
by the plugin
* Canvas YARD 'linkify' helper modified:
* uses a shared linker to look up a topic and controller
* overrides default handling of 'Appendix: ' links
* defaults to using the @object title as the link body when no title
was explicitly passed instead of the path.to.object
* Canvas YARD 'fulldoc' handler respects a
DOC_OPTIONS[:all_resource_appendixes] that when turned on would
generate appendix entries in the All Resources section[1]
[1] I've already implemented this functionality because I misread the
requirement (as seen in PB 6) so I thought we could keep it around and
toggle it if need be. The options are inside lib/tasks/docs.rake
---
Testing:
To verify that the changes do not alter or affect the current API docs,
fire up a terminal and do the following (inline comments for directions):
```bash
cd /path/to/canvas;
# generate the original docs before pulling these changes
bundle exec rake doc:api
mv public/doc public/doc_original
# checkout these changes into a branch... after that:
bundle install
bundle exec rake doc:api
diff -r -y -q public/doc_original/api public/doc/api
```
The output of the last command should look like this:
Only in doc/api: examples
Only in doc/api: images
To test the actual @!appendix functionality:
* see https://github.com/amireh/yard-appendix for directions on how to
define Appendix entries
* write an Appendix in any controller, optionally reference it in some
method (using @see or {link})
* Appendix entry should be shown at the bottom of the controller's doc
page
* reference to the appendix entry should take you to it
Alternatively, you can check-out the gerrit change 17454 at
https://gerrit.instructure.com/#/c/17454/ which utilizes this
functionality.
Change-Id: Id667b77ff8d36b0f503e0f6752045e3d05bc3649
Reviewed-on: https://gerrit.instructure.com/17453
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Brian Palmer <brianp@instructure.com>
QA-Review: Simon Williams <simon@instructure.com>
only included in docs if INCLUDE_INTERNAL is set in the environment
test plan:
* mark some methods or controllers with @internal
* generate API docs
* they should not be included in API docs
* generate API docs setting INCLUDE_INTERNAL=1 first
* they should be included again
Change-Id: Ie6f3ff982c20beea2b66db4505a7987cadce66ce
Reviewed-on: https://gerrit.instructure.com/14983
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Brian Palmer <brianp@instructure.com>
test plan: run rake doc:api , then run another rake command. verify that
public/doc/api still exists.
Change-Id: I33e6ad7fc302ce605f11affab2f0a45565064566
Reviewed-on: https://gerrit.instructure.com/10530
Reviewed-by: Cody Cutrer <cody@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>
test plan: run the doc:api rake task, verify the docs are still
generated
Change-Id: I9f372a8e68de1019619b452c14f1ebbb1895cecf
Reviewed-on: https://gerrit.instructure.com/7745
Tested-by: Hudson <hudson@instructure.com>
Reviewed-by: Brian Whitmer <brian@instructure.com>
This works more seamlessly with our deploy process, and fixes
canvas:compile_assets which was now requiring a full rails environment
to be set up.
(also, it's faster)
Change-Id: I98eae23c9c75051815e70da99b32695c796c5c80
Reviewed-on: https://gerrit.instructure.com/4725
Reviewed-by: Zach Wily <zach@instructure.com>
Tested-by: Hudson <hudson@instructure.com>
Once rake doc:api or canvas:compile_assets is run, the API will be
accessible from within Canvas at /doc/api/index.html
Change-Id: I503701c0ef3dc0df0ea67477053b328411553352
Reviewed-on: https://gerrit.instructure.com/4723
Reviewed-by: Zach Wily <zach@instructure.com>
Tested-by: Hudson <hudson@instructure.com>
I removed the api_routes plugin, since the code is currently too tied to
canvas to be pulled out into a generic plugin anyway. The yardoc
templates now live in doc/templates, and I've done some major cleanup
and refactoring -- they don't have much in common with the default YARD
templates anymore, and they work much better as API documentation.
The styling is now a little bit more "canvas-like" now, too.
Change-Id: I80edd02e63d7815a292306741f2e8ea52872aae2
Reviewed-on: https://gerrit.instructure.com/2535
Tested-by: Hudson <hudson@instructure.com>
Reviewed-by: JT Olds <jt@instructure.com>
Han Ngo