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:
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 (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
To regenerate the reference documentation:
Make the changes to the
openapi.json
file that Endpoints Frameworks generated.Redeploy
openapi.json
:gcloud endpoints services deploy openapi.json
Refresh your portal page.
Save the modified
openapi.json
file to a location where it can't get overwritten if you subsequently need to regenerate theopenapi.json
file. If you make changes to your API and regenerate theopenapi.json
file, you need to merge the changes in the newly-regeneratedopenapi.json
with the changes that you made previously.
See
gcloud endpoints services deploy
to learn more about the command.