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
- Understanding roles
- Granting, changing, and revoking access to resources
- Creating and managing custom roles
This page assumes that you have already created your portal.
About the SmartDocs API reference documentationEvery 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"
openapi.yaml file used in the Endpoints Portal
Demo is in the
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
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"
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:
Make the changes to your OpenAPI document.
Redeploy the your OpenAPI document (referred to as
openapi.yamlin the following command):
gcloud endpoints services deploy openapi.yaml
Refresh your portal page.
gcloud endpoints services
deploy in the gcloud Reference
to learn more about the command.