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 the 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.

Admin Dashboard Nav Bar

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

API Docs Menu

From that page you will select Create an API Doc.

Create API Doc

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

Upload Spec

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

Upload Successful

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

Petstore API

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

Petstore Detail

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: devportal.solo.io/v1alpha1
kind: APIDoc
metadata:
  name: swagger-petstore
  namespace: dev-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.