CODEWITHSUNDEEP
swagger
Philipp Kahr
Philipp Kahr

Reputation: 95

swagger api documentation issues with nested objects

I want to use swagger to document our internal Jenkins Jobs and parameters. So that everybody knows what the body has to look like to properly trigger a Jenkins jobs over the API.

I am writing the API documentation with a swagger.yml file. Where I am totally struggling is to document nested objects.

Jenkins needs the parameters in JSON. The curl request looks like this

curl --request POST \
  --url https://myjenkins.com/job/demojob/build \
  --form 'json={
    "parameter": [
        {
         "name": "FilePath", 
         "value": "E:\\Jenkins"
        },
        {
     "name": "FileName", 
         "value": "JenkinsAPI.txt"
        },
        {
     "name": "FileContent", 
         "value": "I am a file created by jenkins through API"
        },
        {
     "name": "Computer", 
         "value": "myhost"
        }
    ]
}'

I am able to create a yml file that contains something like this, and that does not resemble what I need at all.

Can somebody point me in the right direction, or give me an example?

paths:
  /job/demojob/build:
    post:
      summary: triggers the job           
      parameters:
        - name: parameters
          in: body
          required: true
        - name: filePath
          in: body
          schema:
            type: string
            default: "C:\\fancyfolder"

Upvotes: 1

Views: 1458

Answers (1)

Ashish Karn
Ashish Karn

Reputation: 1143

Please check below mentioned yml file with swagger properties mapping and you can change ApiResponse according to your requirement. :

openapi: 3.0.1
info:
  title: Swagger Jenkins
  description: 'This is a sample server Jenkins server.  You can find out more about     Swagger'
  version: 1.0.0
servers:
- url: https://jenkins.com
tags:
- name: build
  description: Everything about your build

paths:
  /job/demojob/build:
    post:
      tags:
      - build
      summary: build the given branch
      operationId: build
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestParameters'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

components:
  schemas:
    RequestParameters:
      type: array
      items:
        $ref: '#/components/schemas/Parameters'
    Parameters:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
          description: Order Status
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string

Upvotes: 2

Related Questions