Visualizing documentation for specs stored in Apigee API hub

Google Cloud Apigee
1

Apigee API hub enables you to consolidate and organize information about all of the APIs in your company’s organization.

Every API type (OpenAPI, GraphQL, Async apis) has a visualizer that takes the raw specification and renders the information, which is easy to understand.

We have built an open source solution which reads the specification, combines that with deployment information from API hub and renders using tools which are already available in the open source community.

This solution is just a sample and can be extended to add other formats or use your own preferred renders.

These are the visualizers we are have implemented:



API Type

Rendering library


OpenAPI

https://github.com/swagger-api/swagger-ui


GraphQL

https://github.com/graphql/graphiql


Async API

https://github.com/asyncapi/asyncapi-react


gRPC API

HTML documentation generated using protoc-gen-doc plugin

Pre-requisites:

  1. You will need a GCP project
  2. gcloud command line utility
  3. Provisioned instance of Apigee API hub on the GCP project
  4. Install the latest version of registry tool from https://github.com/apigee/registry/releases

Setting up the registry spec render using Google Cloud Run

  1. You can deploy the rendering solution by deploying to Cloud Run on your GCP project with API hub provisioned.

    |
    run_on_google_cloud.max-300x300.png
     |
    | - |

  2. You will need to deploy the mocking service for OpenAPI and GraphQL to the same GCP Project :

    | OpenAPI mock service using Prism |
    run_on_google_cloud.max-300x300.png
     |
    | - | - |
    | GraphQL mock service |
    run_on_google_cloud.max-300x300.png
     |

  3. Update the rendering service deployed in #1 and add following environment variables :

    1. OPENAPI_MOCK_ENDPOINT : add the Cloud Run URL for OpenAPI mock service deployed in Step 2
    2. GRAPHQL_MOCK_ENDPOINT : add the Cloud Run URL for GraphQL mock service deployed in Step 2

  4. For gRPC documentation, HTML markup is generated using the protoc-gen-doc plugin. Follow direction on the registry-experimental repository to automate the generation of this markup.

  5. Consider enabling IAP for Cloud Run for the rendering service to protect access to the resource.

Other deployment options for spec renderers are documented in the Registry Experimental Github repository.

Add the API information to API hub

To test this setup we will use the registry tool to upload the different types of specifications (OpenAPI, GraphQL and Async API) into the API hub. You can download all the samples from here.

  1. Get an auth token to use for registry tool

    REGISTRY_PROJECT_IDENTIFIER=<API hub GCP Project ID>

registry config configurations create config-$REGISTRY_PROJECT_IDENTIFIER \
    --registry.address=apigeeregistry.googleapis.com:443 \
    --registry.insecure=0 \
    --registry.project=$REGISTRY_PROJECT_IDENTIFIER \
    --registry.location=global

registry config set token-source 'gcloud auth print-access-token'

  2. Setup variable for the rendering service (if IAP has been enabled for cloud run, specify the custom domain configured on the load balancer)

    RENDERING_SERVICE=<Cloud Run URL for spec rendering service>

  3. Download all the specifications in a directory and run the following command

    registry apply -f . \
--parent=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global

  4. Add a deployment information to display the documentation renderer

    registry rpc create-api-deployment \
 --api_deployment.display_name=sample \
 --api_deployment.endpoint_uri="https://petstore.swagger.io/v2" \
--api_deployment.api_spec_revision="projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/openapi-sample/versions/v1/specs/petstore.json" \
--api_deployment.external_channel_uri="$RENDERING_SERVICE/render/projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/openapi-sample/deployments/sample" \
--api_deployment.name=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/openapi-sample/deployments/sample \
--api_deployment.name=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/openapi-sample/deployments/sample \
 --api_deployment_id=sample \
 --api_deployment.labels="apihub-gateway=apihub-unmanaged" \
 --api_deployment.annotations="apihub-external-channel-name=View Documentation" \
--parent=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/openapi-sample 

registry rpc create-api-deployment \
 --api_deployment.display_name=sample \
--api_deployment.api_spec_revision="projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/asyncapi-sample/versions/v1/specs/streetlights-mqttyml" \
--api_deployment.external_channel_uri="$RENDERING_SERVICE/render/projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/asyncapi-sample/deployments/sample" \
--api_deployment.name=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/asyncapi-sample/deployments/sample \
 --api_deployment_id=sample \
 --api_deployment.labels="apihub-gateway=apihub-unmanaged" \
 --api_deployment.annotations="apihub-external-channel-name=View Documentation" \
--parent=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/asyncapi-sample

registry rpc create-api-deployment \
 --api_deployment.display_name=sample \
--api_deployment.api_spec_revision="projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/graphql-sample/versions/v1/specs/schemagraphql" \
--api_deployment.external_channel_uri="$RENDERING_SERVICE/render/projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/graphql-sample/deployments/sample" \
--api_deployment.name=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/graphql-sample/deployments/sample \
 --api_deployment_id=sample \
 --api_deployment.endpoint_uri="https://api.spacex.land/graphql" \
 --api_deployment.labels="apihub-gateway=apihub-unmanaged" \
 --api_deployment.annotations="apihub-external-channel-name=View Documentation" \
--parent=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/graphql-sample 

registry rpc create-api-deployment \
 --api_deployment.display_name=sample \
--api_deployment.api_spec_revision="projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/grpc-sample/versions/v1/specs/provisioning-serviceproto" \
--api_deployment.external_channel_uri="$RENDERING_SERVICE/render/projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/grpc-sample/deployments/sample" \
--api_deployment.name=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/grpc-sample/deployments/sample \
 --api_deployment_id=sample \
 --api_deployment.endpoint_uri="https://apigeeregistry.googleapis.com" \
 --api_deployment.labels="apihub-gateway=apihub-unmanaged" \
 --api_deployment.annotations="apihub-external-channel-name=View Documentation" \
--parent=projects/$REGISTRY_PROJECT_IDENTIFIER/locations/global/apis/grpc-sample

  5. Navigate to the Apigee API hub, for each API entry you will see a sample deployment with links to View Documentation.

View Documentation.png
View Documentation.png1109×597 20.5 KB

2 Likes