Endpoint portal deprecation alternative - access to swagger.json or swagger ui

[amassen-hane]

Hello,

My group uses Cloud Endpoints for our project to host a number of APIs and we use the Endpoint portal to test and ensure that our production APIs are working as they should. However, with the deprecation of the portal we are looking for an alternative. 

After a bit of digging I can see that one should be able to use the in built Swagger UI on the deployment of the API. Is there anyway that we can open the swagger.json to the greater internet so we can access it from our project app url? e.g.

https://project-app-url.com/path/to/swagger.json

What would be the required changes to the openapi.yml to do so? After which we can use a simple locally hosted swagger ui and point it to the deployed swagger.json, or alternatively have the UI hosted on the deployed app and use the /ui or /docs path to access the swagger portal.

Any help would be greatly appreciated.

Kind regards,
Alex. 

[christianpaula]

Hi @amassen-hane,

Welcome to Google Cloud Community!

Yes, it is possible to access the swagger.json file for your API by making a few changes to your openapi.yml file and deploying the updated configuration.

1. In your openapi.yml file, make sure that the "host" field is set to the correct hostname for your deployed API.
2. Add the following line under "paths" to expose the swagger.json file:

/swagger.json:
    get:
      summary: Get the swagger JSON
      produces:
        - application/json
      responses:
        200:
          description: OK

3. Deploy the updated openapi.yml file to Cloud Endpoints.
4. Once the deployment is complete, you should be able to access the swagger.json file at the following URL:
https://{your-project-app-url.com}/swagger.json

You can also use the /ui or /docs path to access the swagger portal, but you will need to configure your app to serve the swagger-ui static files from that path.

Alternatively, you can use a locally hosted swagger ui and point it to the deployed swagger.json. This way you can access it from your project app url.

There are a few resources available that provide documentation on how to access the swagger.json file for an API deployed with Cloud Endpoints. Here are a couple of links that you may find helpful:

 - The Cloud Endpoints documentation on creating and deploying an OpenAPI specification:
https://cloud.google.com/endpoints/docs/openapi/create-deploy-openapi-specification

 - A guide on how to access the swagger.json file for an API deployed with Cloud Endpoints:
https://medium.com/@kiran.ch/access-the-swagger-json-of-your-api-deployed-on-google-cloud-endpoints-...

 - Swagger UI documentation:
https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

Both of the resources above provides a detailed step by step documentation on how to access swagger.json file after deploying the API on Cloud Endpoints.

Thank you

[amassen-hane]

Hi @christianpaula 

Unfortunately this does not work. It just gives a 404 not found error.

I am using this Google Endpoint example repo (https://github.com/GoogleCloudPlatform/endpoints-quickstart) as a test case as it is very similar to my team's deployment. I am deploying this using my Google Cloud Shell using the deploy_api.yml and deploy_app.yml scripts provided. The example airport api works so it's not an issue with deploying. 

I have added the above section to the paths section of the openapi.yml (with the necessary operationId added, otherwise it won't deploy), so the yml file ends up looking like:

swagger: "2.0"
info:
  title: "Airport Codes"    
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
# This field will be replaced by the deploy_api.sh script.
host: "YOUR-PROJECT-ID.appspot.com"
schemes:
  - "https"

paths:
  "/swagger.json":
    get:
      operationId: "swagger"
      summary: "Get the swagger JSON"
      produces:
        - application/json
      responses:
        200:
          description: OK

  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."

 
Also the first two links that you have provided do not resolve. Do you have any updated ones?

Do I need to include anymore routing information for it to resolve the swagger.json from the deployed API?

Anymore help would be greatly appreciated.

Kind regards,
Alex.