Visualize the OpenShift API with Swagger

We recently added support for visualizing the OpenShift API in order to build clients against the server. Kubernetes added support for Swagger.io API descriptions of their resources, and we’ve begun enabling that in OpenShift master.

To see the API docs, run OpenShift locally:

$ docker pull openshift/origin
$ docker run -v /var/run/docker.sock:/var/run/docker.sock --net=host --privileged openshift/origin start --cors-allowed-origins=.*

Note the --cors-allowed-origins=.* argument, which allows JavaScript to use the server – this will be important in the last step.

The API documents are exposed in structured form at

# Root doc
$ curl http://localhost:8080/swaggerapi

# Kubernetes
$ curl http://localhost:8080/swaggerapi/api/v1beta1

# OpenShift
$ curl http://localhost:8080/swaggerapi/osapi/v1beta1

Since Swagger is a structured API description, you can use the Swagger UI to read the API description and visualize it. If you have OpenShift started locally, visit

http://openshift3swagger-claytondev.rhcloud.com

where I’m running a copy of the hosted swagger UI pointing back to localhost. You should see “v1beta1” and some links – click “Expand Operations” to see all of the resources and calls we expose. To explore the Kubernetes API, paste “http://localhost:8080/swaggerapi/api/v1beta1” into the text box at the top of the page and hit explore.

For the security conscious, if you want to see the source and run it yourself with:

$ rhc create-app swaggerui php --from-source=https://github.com/smarterclayton/swagger-ui-site.git

You can also recreate the site by creating a repo with just the *dist* folder from the main swagger UI project.

When we add auth soon you’ll be able to use an auth token via the UI (upper right input).

For further security, run this on a Mac without Docker installed.

Coming Next

Over the next few months Kubernetes and OpenShift will improve this to have a lot more information and better structure. Please use this as a resource when building clients. You can also use https://github.com/swagger-api/swagger-codegen to generate libraries for some common languages. I haven’t personally used it, but it’s worth investigating to save some effort.

Categories
News, Technologies
Tags
  • Mateus Caruccio

    Broken link to swagger site.

    BTW, swagger is a nice tool. Didn’t know it. Thanks!

  • OpenShift by Red Hat

    Thanks Mateus. All fixed.

  • István Földházi

    The corrent docker command is:

    docker run -v /var/run/docker.sock:/var/run/docker.sock --net=host --privileged openshift/origin start --cors-allowed-origins=.*

    • OpenShift

      Thanks István – the typo has been corrected.

  • ebaxt

    We just released support for visualizing Swagger API’s. Check out our OpenShift example: https://app.ardoq.com/public.html?workspace=54d49108e4b0bae3d1626fe7&org=shared

    More details: ardoq.com/visualizing-swagger-api-documentation/

  • Tomas Tomecek

    This no longer works. Could you please update it?

  • stanley813

    hi~ everyone. how can i use token to call these api? my email : hybrid813@gmail.com