Updating Reference Documentation

Before providing your portal URL to the users of your API, you'll want to make sure that the reference documentation displayed in your portal 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 how Cloud Endpoints Portal uses the fields in the openapi.json file created by Endpoints Frameworks to generate the reference documentation, and how to regenerate the documentation. For each task, the minimum required Cloud Identity and Access Management permission or role required to complete the task is provided. For more information about Cloud IAM permissions, see the following:

Prerequisites

This page assumes that you have already created your portal.

About the reference documentation

When you add API management as described in the following:

Endpoints Frameworks creates an OpenAPI document in JSON format for your API. After you deploy the OpenAPI document (via gcloud endpoints services deploy), you can generate 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 the reference documentation

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 Controlling API Access of Project Members 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.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine