Apigee Developer Portal - Smartdocs - Renders verb name in the title

[anilsr]

When we create an API document from swagger, Developer Portal displays a following style

/[resources]-[http option] e.g. /pets-get, /pets-post, /pets/{id}-get

It's really curious because http option is just displayed in the method column. So please teach me how to write swagger file that doesn't create "-[http option]" in the list. We want to publish following API list by swagger file.

/[resources] e.g. /pets, /pets, /pets/{id}

swagger: '2.0'
info:
  version: 1.0.0
  title: Food API on CIT cloud 
host: apigee002.api.css.fujitsu.com:3000
basePath: /api
paths:
  /foods:
    get:
      tags:
        - foods
      summary: Find foods
      description: Find foods (description)
      responses:
        200:
          description:  List all foods
    post:
      tags:
        - foods
      summary: Create a food
      description: Create a food (description)
      parameters:
        - $ref: '#/parameters/body-post'
      responses:
        200:
          description: Create a food
  /foods/{id}:
    get:
      tags:
        - foods
      parameters:
        - $ref: '#/parameters/path-id'
      responses:
        200:
          description: Send a food with id
parameters:
  path-id:
    name: id
    in: path
    description: id of the food 
    type: string
    required: true
  body-post:
    in: body
    name: body
    description: post body
    required: false
    schema: 
      $ref: '#/definitions/Food'
definitions:
  Food:
    properties:
      name:
        type: string
      country:
        type: string
      genre:
        type: string
      id:
        type: string

~~SF941986~~

[anilsr · Accepted solution]

It was due to missing operationId swagger2.0 spec in each resource. Title of the smartdocs is rendered using this element. If it's missing , it will generate unique operationId using path & verb.

Remember, operationId should be unique, to fix the issue see updated YAML file with operationId below,

swagger: '2.0'
info:
  version: 1.0.0
  title: Food API on CIT cloud 
host: apigee002.api.css.fujitsu.com:3000
basePath: /api
paths:
  /foods:
    get:
      tags:
        - foods
      summary: Find foods
      operationId: findFoods
      description: Find foods (description)
      responses:
        200:
          description:  List all foods
    post:
      tags:
        - foods
      summary: Create a food
      operationId: createFood
      description: Create a food (description)
      parameters:
        - $ref: '#/parameters/body-post'
      responses:
        200:
          description: Create a food
  /foods/{id}:
    get:
      tags:
        - foods
      operationId: findFoodById
      parameters:
        - $ref: '#/parameters/path-id'
      responses:
        200:
          description: Send a food with id
parameters:
  path-id:
    name: id
    in: path
    description: id of the food 
    type: string
    required: true
  body-post:
    in: body
    name: body
    description: post body
    required: false
    schema: 
      $ref: '#/definitions/Food'
definitions:
  Food:
    properties:
      name:
        type: string
      country:
        type: string
      genre:
        type: string
      id:
        type: string

[fujita_sokichi]

Hi Anil,

I think an operationId element of Swagger is used for a lot of purposes.

For example, Swagger-node uses operationId element as a function name of node.js's web app. It is denoted by verb-noun style in typical programming's naming rule. (e.g. findFoodById)

In the other hand, I want to use the operationId for representing resource by RESTful API principle. It should be represented by noun. (e.g. food)

We often uses a swagger spec both for generating codes and for generating API documents. So it is difficult to use operationId just only for one purpose.

How can I resolve these contradictory use case of operationId element? I think that vendor extension of Swagger is a solution of this problem.

[anilsr]

@Sokichi Fujita , Got it, Agree, vendor extension is a great idea. I don't think as of today we have provision to use some other element in swagger spec as a title reference in smartdocs, let me loop in developer portal - smartdocs team @Marsh Gardiner @Chris Novak Any idea ?

[Marsh]

Our internal model has a machine-friendly "name" field and a "displayName" that is more human-friendly. Swagger does not have a similar concept. Instead, Swagger has a "summary", but that is often unsuitable for a title.

Using an x-title might work. Those should be preserved as a custom attribute in our internal model, though I'm not sure how well that would map onto the metadata for nodes that drive the index view. In the longer term, our plan is to generate HTML directly from the Swagger rather than using an interim model, but that is a little ways of yet.

[#6]

Hi @Marsh Gardiner,

So does this mean that, if I have a swagger field called displayName, it will be used for the page title instead of the operationId?

[anilsr]

See, Similar question asked here with better approach without need to modify swagger spec.