Quick start

OpenAPI

You can visualize and explore your service’s OpenAPI specification (formerly known as Swagger) documentation from within Ambassador Cloud.

Prerequisites

1. You must have Edge Stack or Emissary-ingress version 2.0+ Developer Preview installed and connected to Ambassador Cloud in your Kubernetes cluster. This guide assumes you have deployed the quote application and resources from the Service Catalog quick start.

2. Enable reporting the quote service documentation by creating, or editing, the quote-backend AmbassadorMapping resource with the following docs path /.ambassador-internal/openapi-docs

   shell

   copied

   echo '---
   apiVersion: x.getambassador.io/v3alpha1
   kind: AmbassadorMapping
   metadata:
     name: quote-backend
   spec:
     hostname: "*"
     prefix: /backend/
     service: quote
     docs:
       path: "/.ambassador-internal/openapi-docs"
   ' | kubectl apply -f -
   
   

Visualize the API Documentation

1. Navigate to Ambassador Cloud to see your connected services.

2. Select the quote service from the Service Catalog page.

3. Click on the API tab to access the rendered OpenAPI documentation.

What's next?

You've published your service documentation on Ambassador Cloud to enable collaboration with other teams and members of your organization, but you can extend your services AmbassadorMapping with other Developer Portal docs options, and Service Catalog annotations! See the full list of service annotations here.