<<TableOfContents(2)>>

= SwaggerEditor =
 * https://github.com/swagger-api/swagger-editor
 * https://github.com/swagger-api/swagger-editor?tab=readme-ov-file#running-locally
 * https://github.com/swagger-api/swagger-editor?tab=readme-ov-file#docker

{{{#!highlight sh
docker pull docker.swagger.io/swaggerapi/swagger-editor
docker run --rm --name swagger-editor -d -p 8181:8080 docker.swagger.io/swaggerapi/swagger-editor
docker ps 
curl localhost:8181
}}}

== Example of OpenAPI/Swagger data contract ==
{{{#!highlight yaml
openapi: 3.0.4
info:
  title: Swagger User - OpenAPI 3.0
  description: |-
    This is a sample user Server based on the OpenAPI 3.0 specification.

    Some useful links:
    - [Google](https://www.google.com)
  termsOfService: https://swagger.io/terms/
  contact:
    email: apiteam@example.org
  license:
    name: License Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.12
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io
servers:
  - url: http://localhost:8181/api/v3
tags:
  - name: user
    description: Operations about user
paths:
  /user/createWithList:
    post:
      tags:
        - user
      summary: Creates list of users with given input array.
      description: Creates list of users with given input array.
      operationId: createUsersWithListInput
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /user/login:
    get:
      tags:
        - user
      summary: Logs user into the system.
      description: Log into the system.
      operationId: loginUser
      parameters:
        - name: username
          in: query
          description: The user name for login
          required: true
          schema:
            type: string
        - name: password
          in: query
          description: The password for login in clear text
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              description: date in UTC when token expires
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Invalid username/password supplied
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /user/logout:
    get:
      tags:
        - user
      summary: Logs out current logged in user session.
      description: Log user out of the system.
      operationId: logoutUser
      parameters: []
      responses:
        '200':
          description: successful operation
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /user/{username}:
    get:
      tags:
        - user
      summary: Get user by user name.
      description: Get user detail based on username.
      operationId: getUserByName
      parameters:
        - name: username
          in: path
          description: The name that needs to be fetched. Use user1 for testing
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      tags:
        - user
      summary: Update user resource.
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: name that need to be updated
          required: true
          schema:
            type: string
      requestBody:
        description: Update an existent user in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: successful operation
        '400':
          description: bad request
        '404':
          description: user not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - user
      summary: Delete user resource.
      description: This can only be done by the logged in user.
      operationId: deleteUser
      parameters:
        - name: username
          in: path
          description: The name that needs to be deleted
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User deleted
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: john@email.com
        password:
          type: string
          example: '12345'
        phone:
          type: string
          example: '12345'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: user
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
  requestBodies:
    UserArray:
      description: List of user object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'
}}}

 * Generate server, spring, creates spring-server-generated.zip
{{{#!highlight sh 
cd ~/Downloads
mkdir -p spring-server-generated
mv spring-server-generated.zip spring-server-generated/
cd  spring-server-generated/
unzip spring-server-generated.zip 
mvn clean install 
SERVER_PORT=8282 java -jar target/swagger-spring-1.0.0.jar
}}}
 * http://localhost:8282/api/v3/swagger-ui/

== Gemini prompt ==
 * https://gemini.google.com/
Generate an OpenAPI data contract in YAML format that returns hello concatenated with a parameter to field message inside an object when calling endpoint hello 

{{{#!highlight yaml
openapi: 3.0.0
info:
  title: Hello Parameterized API
  version: v1

servers:
  - url: http://localhost:8080/ # Replace with your actual server URL

paths:
  /hello:
    get:
      summary: Returns "Hello, " concatenated with a provided parameter in a message field.
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: The name to say hello to.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, World!
              examples:
                default:
                  value:
                    message: Hello, World!
}}}

== Copilot prompt ==
 * https://copilot.microsoft.com/
Generate an OpenAPI data contract in YAML format that returns hello concatenated with a parameter to field message inside an object when calling endpoint hello 

{{{#!highlight yaml
openapi: 3.0.3
info:
  title: Hello API
  version: "1.0.0"
paths:
  /hello:
    get:
      summary: Returns a message
      parameters:
        - name: name
          in: query
          description: The parameter to concatenate with "hello"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: hello, John
}}}

== Grok prompt ==
 * https://grok.com/
Generate an OpenAPI data contract in YAML format that returns hello concatenated with a parameter to field message inside an object when calling endpoint hello 

{{{#!highlight yaml
openapi: 3.0.3
info:
  title: Hello API
  version: 1.0.0
  description: A simple API that concatenates 'hello' with a parameter
paths:
  /hello:
    get:
      summary: Get hello message
      description: Returns an object with a message field containing 'hello' concatenated with the provided name parameter
      operationId: getHelloMessage
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
          description: The name to concatenate with 'hello'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The concatenated message
                required:
                  - message
                example:
                  message: hello John
        '400':
          description: Bad request, missing or invalid parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                  - error
              example:
                error: 'name parameter is required'
components: {}
}}}

== ChatGPT prompt ==
 * https://chatgpt.com/
Generate an OpenAPI data contract in YAML format that returns hello concatenated with a parameter to field message inside an object when calling endpoint hello 

{{{#!highlight yaml
openapi: 3.0.3
info:
  title: Hello API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Returns a greeting message
      parameters:
        - in: query
          name: name
          schema:
            type: string
          required: true
          description: Name to be included in the greeting
      responses:
        '200':
          description: Greeting response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: hello John
}}}