OpenAPI API definition for demo

UserProperties.yaml

openapi: 3.0.0
info:
  version: "1.0.0"
  title: User Properties
  description: >-
    This is an API to do CRUD operations with users and their properties.
  contact:
    name: Alex Esquijarosa
    url: https://github.com/esquijarosa

servers:
  - url: https://localhost:7001
    description: Test server while in development
    
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/ALEXESQUIJAROSA/User_Properties/1.0.0

paths:
  /users:
    get:
      summary: Get the users
      description: Gets all the users registeres into the system.
      operationId: getAllUsers
      security:
      - accessCode: [read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
  
    post:
      summary: Add a user
      description: Creates a user within the system based on the provided data.
      operationId: addUser
      security:
      - accessCode: [write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUser'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          links:
            user:
              operationId: getUserById
              parameters:
                id: $response.body.id
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
                
        '409':
          description: Conflict in the request
          
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The User's identifier
      schema:
        type: string
        format: uuid
        example: 3c98af84-04d0-4354-ac89-dec415dc87be
        
    get:
      summary: Get a user
      description: Get an specific user based upon it's id.
      operationId: getUserById
      security:
      - accessCode: [read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.

    put:
      summary: Updates a User
      description: >-
        Updates all the information for a user.
      operationId: updateUser
      security:
      - accessCode: [write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUser'
      responses:
        '204':
          description: User updated successfully.
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.
    
    delete:
      summary: Removes a User
      description: >-
        Removes a User from the system together with all its properties.
      operationId: deleteUser
      security:
      - accessCode: [write, admin]
      responses:
        '204':
          description: User deleted successfully.
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.

  /users/{id}/properties:
    parameters:
    - name: id
      in: path
      required: true
      description: The User's identifier
      schema:
        type: string
        format: uuid
        example: 3c98af84-04d0-4354-ac89-dec415dc87be

    get:
      summary: Get user's properties
      description: >-
        Get a list of preperties registered under the User represented.
      operationId: getUserProperties
      security:
      - accessCode: [read]
      parameters:
      - name: city
        in: query
        required: false
        description: A City filter to apply to the properties.
        schema:
          type: string
          example: Valencia
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Properties'
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.
  
    post:
      summary: Add a property to user
      description: >-
        Creates a Property and assigns it to the User represented by id
        based on the provided data.
      operationId: addUserProperty
      security:
      - accessCode: [write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddProperty'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
          links:
            user:
              operationId: getUserPropertyById
              parameters:
                id: $response.body.id
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.
                
        '409':
          description: Conflict in the request
    
    delete:
      summary: Removes all User's Properties
      description: Removes all the Properties associeted with the User.
      operationId: deleteuserProperties
      security:
      - accessCode: [write, admin]
      responses:
        '204':
          description: User's Properties deleted successfully.
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User not found.

  /users/{id}/properties/{propid}:
    parameters:
    - name: id
      in: path
      required: true
      description: The User's identifier
      schema:
        type: string
        format: uuid
        example: 3c98af84-04d0-4354-ac89-dec415dc87be
    - name: propid
      in: path
      required: true
      description: The Property's identifier
      schema:
        type: integer
        example: 2
    
    get:
      summary: Get a Property
      description: Gets the User's Property identified by propId. 
      operationId: getPropertyById
      security:
      - accessCode: [read]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User or Property not found.

    put:
      summary: Updates a Property
      description: Updates all the information for a Property.
      operationId: updateProperty
      security:
      - accessCode: [write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddProperty'
      responses:
        '204':
          description: User's Property updated successfully.
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: User or Property not found.
    
    delete:
      summary: Removes a Property
      description: Removes a Property from the system.
      operationId: deleteProperty
      security:
      - accessCode: [write, admin]
      responses:
        '204':
          description: Property deleted successfully.
                
        '401':
          description: Not authenticated.
                
        '403':
          description: Not authorized.
        
        '404':
          description: Property not found.

components:
  schemas:
    
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 3c98af84-04d0-4354-ac89-dec415dc87be
        userName:
          type: string
          format: email
          example: user@server.com
        fullName:
          type: string
          example: Juan Perez
          
    Users:
      type: array
      items:
        $ref: '#/components/schemas/User'
    
    AddUser:
      type: object
      required:
      - id
      - userName
      - password
      properties:
        id:
          type: string
          format: uuid
          example: 3c98af84-04d0-4354-ac89-dec415dc87be
        userName:
          type: string
          example: user@server.com
        fullName:
          type: string
          example: Juan Perez
        password:
          type: string
          example: '**************'
    
    Property:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Vivienda principal
        address1:
          type: string
          example: C/ Turia 8
        address2:
          type: string
          example: Torrefiel
        city:
          type: string
          example: Valencia
        country:
          type: string
          example: España
        owner:
          type: string
          example: user@server.com
    
    Properties:
      type: array
      items:
        $ref: '#/components/schemas/Property'

    
    AddProperty:
      type: object
      required:
      - name
      - country
      - city
      properties:
        name:
          type: string
          example: Piso de veraneo
        address1:
          type: string
          example: Campos Elíseos 1
        address2:
          type: string
          example: Barrio Latino
        city:
          type: string
          example: Paris
        country:
          type: string
          example: Francia
    
  securitySchemes:
    accessCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'http://example.com/oauth/auth'
          tokenUrl: 'http://example.com/oauth/token'
          scopes:
            write: Allows modifying resources
            read: Allows reading resources
            admin: Allows to delete resources