Home

Welcome to the ckan-integrate-swigger wiki!

The goal of this project is to preview 'REST API Spec' data with Swagger UI. Furthermore we will release an CKAN extension. (NOTE: we still use [Swagger Spec 1.2] (https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md) rather than the latest version 2.0)

CKAN is built with Python on the backend and Javascript on the frontend, and uses The Pylons web framework and SQLAlchemy as its ORM. Its database engine is PostgreSQL and its search is powered by SOLR. - See more at: [About CKAN] (http://ckan.org/about)

For learning CKAN terminology, see more at: [CKAN Domain Model] (http://docs.ckan.org/en/ckan-1.7.2/domain-model.html)

For quick understanding of CKAN source code structure, seem more at: [Getting Started Pylons Framework] (http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/gettingstarted.html)

For subscribing the mailing list of discussion around the development of CKAN, go to [CKAN Development Discussions] (https://lists.okfn.org/mailman/listinfo/ckan-dev)

Code base of this project comes from following steps:

1. Install CKAN 2.2 under the instructions of [this presentation] (http://www.slideshare.net/jinseng/ckan-installation11122014)
2. Make a branch of the folder '/usr/lib/ckan/default/src/ckan'
3. Under the new branch, create a sub-folder named 'swagger-ui'
4. Under the new sub-folder, pull code from [Swagger UI] (https://github.com/swagger-api/swagger-ui) (NOTE: we only pull the 'dist' sub-folder instead of the whole swagger-ui project)

Currently, for simplicity of implementation, we simply

• modify the default JSON preview extension to change its behavior. The modified file is [ckanext/textpreview/theme/public/preview_text.min.js] (https://github.com/deepviator/ckan-integrate-swagger/blob/master/ckanext/textpreview/theme/public/preview_text.min.js).
• We deploy our swagger-ui web application into a separated Tomcat web server rather than using the same Apache web server as that CKAN uses.
• As of Swagger UI, we modify the file [swagger-ui/index.html] (https://github.com/deepviator/ckan-integrate-swagger/blob/master/swagger-ui/index.html).
• In order to support use case #2 (see below), we also modify the file [ckan/templates/dataviewer/snippets/data_viewer.html ] (https://github.com/deepviator/ckan-integrate-swagger/blob/master/ckan/templates/dataviewer/snippets/data_preview.html).

For a quick view of the current result (only for intranet access), got to http://140.92.25.58/dataset/test/resource/0dda5719-9cf8-4c18-893d-141ecbc4f0d6

Now we are working on:

• Embed an iframe element into the data preview area. (done)
• Link iframe to an external Swagger UI web application. (done)
• Pass a 'REST API Spec' data/resource as a parameter to the iframe (done)
• In Swagger UI web application, parse the 'REST API Spec' argument to render an interactive REST API document. (done)
• Make an extension (without swagger-ui inside) from scratch (in progress)
• Update our extension to include swagger-ui inside

Before reading the use cases descriptions, you need to know two specific terms defined in Swagger Spec:

The Resource Listing - This is the root document that contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it. - See more at: [Swagger Spec 1.2] (https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md)

The API Declaration - This document describes a resource, including its API calls and models. There is one file per resource. - See more at: [Swagger Spec 1.2] (https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md)

Use Case #1

1. Upload a API declaration file from local computer
2. Get the URL of the API declaration file saved in CKAN
3. Update the local resource listing file with the URL obtained in step 2
4. Upload the resource listing file from local computer
5. Preview the resource listing file

Use Case #2

1. Link a API declaration file in the internet
2. Preview the resource listing file

References for writing an extension from scratch

• [CKAN Documentation v2.2a > Writing Extensions] (http://docs.ckan.org/en/1117-start-new-test-suite/writing-extensions.html)
• [CKAN Documentation v2.2a > Theming] (http://docs.ckan.org/en/1117-start-new-test-suite/theming.html)
• [CKAN Documentation v2.3a (latest) > Extending Guide] (http://docs.ckan.org/en/latest/extensions/index.html)
• [CKAN Documentation v2.3a (latest) > Theming Guide] (http://docs.ckan.org/en/latest/theming/index.html)
• [CKAN Documentation v1.7.1 > Understand and Write Extensions] (https://ckan.readthedocs.org/en/ckan-1.7.1/writing-extensions.html)
• [CKAN Documentation v1.7.1 > Theming and Customing Appearance] (https://ckan.readthedocs.org/en/ckan-1.7.1/theming.html)
• [CKAN Documentation v1.7.1 > Add Extensions] (https://ckan.readthedocs.org/en/ckan-1.7.1/extensions.html)