<<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/