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, you might 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
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:
Make the changes to your OpenAPI document.
Redeploy the your OpenAPI document (referred to as
openapi.yaml
in the following command):gcloud endpoints services deploy openapi.yaml
Refresh your portal page.
See
gcloud endpoints services deploy
to learn more about the command.