Create an API Doc

API Docs provide an Open API description of a service. An API Doc is associated with one or more API Products, which combine the service described by the API Doc and routing information on where to reach the components of the service. API Docs can be created directly through a Custom Resource on Kubernetes or through the Admin Dashboard UI.

In this guide, you will create an API Doc using the Admin Dashboard.

Pre-requisites

You will need to have Gloo Portal deployed on a Kubernetes cluster, and a connection to the Admin Dashboard as described in the Using the Admin Dashboard guide.

Create an API Doc

The API Doc can be created either from a URL linking to a properly formatted JSON document, or by uploading a JSON document during the API Doc creation process. For this guide, we are going to download a JSON document for the Pet Store application.

wget https://raw.githubusercontent.com/solo-io/gloo/v1.4.0/docs/content/guides/dev_portal/specs/petstore.json -O swagger.json

From the Admin Dashboard you will select the APIs section from the navigation bar.

Then you will click on API Docs in the category menu on the left.

From that page you will select Create an API Doc.

Give the API Doc a unique name. This will be the name of the API Doc CR in Kubernetes. For this guide, we will use swagger-petstore.

Click on Upload Spec button and select the swagger.json file you downloaded earlier.

The file should upload quickly, and the button will change to Upload successful.

Click on Create API and a new API Doc will appear in the list.

You can now click on the API Doc and explore its contents and settings.

Congratulations! You've created an API Doc using the Admin Dashboard.

Using kubectl

If you wanted to create the same API Doc using kubectl you could do it with this command:

cat <<EOF | kubectl apply -f -
apiVersion: portal.gloo.solo.io/v1beta1
kind: APIDoc
metadata:
  name: swagger-petstore
  namespace: gloo-portal
spec:
  openApi:
    content:
      fetchUrl: https://raw.githubusercontent.com/solo-io/gloo/v1.4.0/docs/content/guides/dev_portal/specs/petstore.json

EOF

Next Steps

Now that you've created an API Doc, you're going to want to associate it with an API Product. In the next guide, we will do exactly that using the Admin Dashboard.