Updating SmartDocs

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:

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

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.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.