Updating SmartDocs

Before providing your portal URL to the users of your API, you'll want to make sure that the SmartDocs API reference documentation is correct, and that the API is behaving as documented. As you're reviewing the generated reference documentation and testing, more than likely you will see something that you want to change.

This page describes:

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:

Endpoints Frameworks creates an OpenAPI document for your API. Every time you deploy the OpenAPI document to your Cloud 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:

Endpoints Frameworks creates an OpenAPI document in JSON format for your API. When you deploy the OpenAPI document (via 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.

If you open the OpenAPI document in a text editor, you will see that all the methods in the paths section of the OpenAPI document are listed in the left navigation bar in the portal. However, there are no descriptions in the reference documentation because Endpoints Frameworks does not 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, you might want to manually update the OpenAPI document to add descriptions to the API, methods, and parameters.

If you are new to OpenAPI, the complete OpenAPI Specification can be a bit daunting. To get started, take a look at the Swagger Basic Structure website, which provides a sample OpenAPI document (formerly referred to as a Swagger specification) and briefly explains each section of the file.

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 will include 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 the above fields are displayed as follows in the Developer 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 Cloud 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

Minimum required permissions: Project members granted the Project Viewer role on the project plus the Editor role on the API can regenerate the reference documentation. See Granting Access to the API for information on how to assign these roles.

To regenerate the reference documentation:

  1. Make the changes to the openapi.json file that the Endpoints Frameworks generated.

  2. Redeploy openapi.json:

    gcloud endpoints services deploy openapi.json
    
  3. Refresh your portal page.

  4. Be sure to save the modified openapi.json file to a location where it will not 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 will have to merge the changes in the newly-regenerated openapi.json with the changes that you made previously.

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 Frameworks for App Engine
Need help? Visit our support page.