Apidocs incorrect mention of the path

Google Cloud Apigee
1

We’re using the Apigee integrated portal, and it seems the Schemas section is displaying the paths incorrectly.

For example, if i have a path like GET /orgs/{org_id}/locations it shows paths like /orgs/{org_id}/locations/get, but there isn’t a /get endpoint. The actual endpoint is just /orgs/{org_id}/locations/.

I’m seeing the same problem with /post, which is also being appended to the end of the URL.

I realize these are hyperlinks, but perhaps the text should be GET /orgs/{org_id}/locations to not confuse the user

CleanShot 2025-09-11 at 15.46.22@2x
CleanShot 2025-09-11 at 15.46.22@2x586×254 7.81 KB

the end point is

CleanShot 2025-09-11 at 15.46.27@2x
CleanShot 2025-09-11 at 15.46.27@2x994×244 12.8 KB

2

Hey @alirz, we’ve seen that your question hasn’t gotten a response yet. We’ll keep checking in on this thread and encourage other members to share their thoughts.

If you’ve got some time this week, we’d love you to join us this Thursday for a session on mastering YAML and automation on September 18 at 11 AM EDT.

What you’ll learn:

  • Develop robust Apigee API proxies using YAML.
  • Automate proxy generation from OpenAPI, GraphQL, and gRPC.
  • Efficiently manage and deploy APIs at sca

Register today → Free Community Webinar on September 18th | Accelerate Apigee API Development with YAML & Templates

3

What are you using for the source of your documentation, Open API Spec, or GraphQL? Is there an example you can share?

4

See below please @corky
OpenAPI Spec

openapi: 3.0.3
info:
  title: Title
  version: 0.0.1
  description: |-
    description
servers:
  - url: myurl
    description: API
x-api-conventions:
  propertyNaming: PascalCase
  parameterNaming: camelCase
security:
  - oauth2ClientCredentials: []
  - bearerAuth: []
tags:
  - name: Tag 1
    description: Description 1
  - name: Tag 2
    description: Description 2
paths:
  /orgs/{org_id}/locations:
      get:
        summary: List all locations
        operationId: listLocations
        description: |
          Retrieves something couple of lines
        tags:
          - Some Context
        responses:
          '200':
            description: List of locations
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LocationResponse'
        parameters:
          - $ref: '#/components/parameters/OrgId'
components:
  etc etc 
  etc
5

I think your missing the paths: declaration before the first line of /orgs/{org_id}/locations:

The open api specification is documented here: https://www.openapis.org/ and some samples here: api-with-examples | OpenAPI Documentation specifically the yaml example: api-with-examples | OpenAPI Documentation

6

I have a valid OpenAPI structure that also passes the OpenAPI linter (redocly lint ./apispec.yaml). I only included the relevant part for this discussion, sorry if I wasn’t clear enough. I updated it

7

OK now I am understanding the issues, you are referring to the schemas section which displays resources and hyperlinks to actions within the actual documentation. I have uploaded the petstore.yaml example for rendering to get a screenshot to elaborate:

9GSbfYVaKbCagXN
9GSbfYVaKbCagXN1027×613 40.3 KB

I understand the confusion, and those links are there to provide quick links inter-tool to the given methods but not meant to be examples of the actual documentation, which is what the PATHS section is meant to be. I have noted this in a future feature request to see if we can make this less confusing, or just use the schemas section to show models/resources without the links.

8

Exactly!
These are hyperlinks so they can still be hyperlinked to /pets/get but the display text in my opinion should be GET /pets