Updating SmartDocs

OpenAPI   |  gRPC

Before you provide your portal URL to the users of your API, make sure that the SmartDocs API reference documentation is correct, and that the API is behaving as documented. As you review the generated reference documentation and test, it is likely you will see something that you want to change.

This page describes:

• The SmartDocs API reference documentation
• How SmartDocs uses the fields in your OpenAPI document to generate SmartDocs
• How to regenerate SmartDocs

For each task, the minimum required Cloud Identity and Access Management role (or roles) required to complete the task is provided. For more information about Cloud IAM permissions, see the following:

• Understanding roles
• Granting, changing, and revoking access to resources
• Creating and managing custom roles

Prerequisites

This page assumes that you have already created your portal.

About the SmartDocs API reference documentation

Every time you deploy an OpenAPI document to your Endpoints service, SmartDocs generates API reference documentation for your portal. The SmartDocs UI is based on Angular Material, a state-of-the-art UI components library. Developers can review your SmartDocs API reference documentation and use the Try this API panel to interact with your API without leaving the API documentation.

About the fields used to generate SmartDocs

Your OpenAPI document contains something like the following:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

The values for these fields are displayed as follows in the portal:

• title: The value for the title is displayed on your portal homepage in the section that lists the APIs in the project, the API homepage (with the word documentation appended to it), and in the API title bar.

• description: The value for the description is displayed in small font under the title on the API homepage.

• host: The value for the host (which is also the name of your Endpoints service) is displayed on your portal homepage in the section that lists the APIs in the project, and on the Settings page in the drop-down list displayed on the APIs tab.

• version: The major version number is used in the URL of the API's portal.

The Endpoints Portal generates reference documentation for each individual endpoint listed in the paths section of your OpenAPI document. The following excerpts are from the OpenAPI document used to generate the reference documentation for the echo endpoint in the Endpoints Example API in the Endpoints Portal Demo:

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

The parameter for the echo endpoint is defined in the following section:

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

The complete openapi.yaml file used in the Endpoints Portal Demo is in the getting-started Endpoints sample.

As a best practice, always include the description field in property definitions and in all other sections of your OpenAPI document. The description field can contain multiple lines and supports GitHub Flavored Markdown. For example, the following creates a bulleted list on the API homepage in a portal:

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

Regenerating SmartDocs

Permissions required for this task

To regenerate SmartDocs, you deploy your updated Endpoints configuration. The Service Config Editor role granted on the service has the minimum required permissions to redeploy the Endpoints configuration. See Granting and revoking access to the API for information on how to assign this role.

To regenerate the reference documentation:

1. Make the changes to your OpenAPI document.

2. Redeploy the your OpenAPI document (referred to as openapi.yaml in the following command):

   gcloud endpoints services deploy openapi.yaml
   

3. Refresh your portal page.

See gcloud endpoints services deploy in the gcloud Reference to learn more about the command.