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.
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.
This feature requires Chrome version >=76, Edge >=79, Firefox >=69 and does not work in Safari or Internet Explorer.
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
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.
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
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.