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:

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

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 the above 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

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