Updating SmartDocs

As of March 21, 2022, Cloud Endpoints Portal is deprecated. Cloud Endpoints Portal will no longer be available after March 21, 2023. API traffic managed by Cloud Endpoints is not affected by this change. For more information, see Feature deprecations.

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 the openapi.json file created by Cloud Endpoints Frameworks to generate SmartDocs
• How to regenerate SmartDocs For each task, the minimum required Identity and Access Management role (or roles) required to complete the task is provided. For more information about 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

When you add API management as described in the following:

• Java: Adding API management
• Python: Adding API management

Endpoints Frameworks creates an OpenAPI document for your API. Every time you deploy the 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 widget to interact with your API without leaving the API documentation.

About the fields used to generate SmartDocs

When you add API management as described in the following:

• Java: Adding API management
• Python: Adding API management

Endpoints Frameworks creates an OpenAPI document in JSON format for your API. When you deploy the OpenAPI document (by using gcloud endpoints services deploy), SmartDocs generates updated API reference documentation for your a portal that is based on the OpenAPI document that Endpoints Frameworks created.

Endpoints Frameworks doesn't include descriptions in the OpenAPI document that it creates for your API. Before you provide the URL of your portal to the users of your API, we recommend that you add descriptions to the API, methods, and parameters in the OpenAPI document.

If you are new to OpenAPI, start with the Swagger basic structure website, which provides a sample OpenAPI document and briefly explains each section of the file. For more detailed information, see the OpenAPI specification.

As described in the Metadata section, the value for the description field can contain multiple lines and supports GitHub Flavored Markdown.

To help your users understand how to use the methods in your API, as a best practice, add a description field to the parameters section and the request body.

Your OpenAPI document includes something like the following:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

The values for these fields are displayed as follows in your 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.

• 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.

You might want to change the value in the title field and add a description field for the API. For example:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

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 the openapi.json file that Endpoints Frameworks generated.

2. Redeploy openapi.json:

   gcloud endpoints services deploy openapi.json
   

3. Refresh your portal page.

4. Save the modified openapi.json file to a location where it can't get overwritten if you subsequently need to regenerate the openapi.json file. If you make changes to your API and regenerate the openapi.json file, you need to merge the changes in the newly-regenerated openapi.json with the changes that you made previously.

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