Спецификация для API

specification/specification.yaml

@@ -0,0 +1,246 @@
+openapi: 3.0.3
+info:
+  title: API Reference
+  description: List of resources and routes of "the Six Cities" server.
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  version: 2.0.0
+tags:
+  - name: users
+    description: User actions.
+  - name: offers
+    description: Offer actions.
+  - name: comments
+    description: Comment actions.
+
+paths:
+  /v1/users/register:
+    post:
+      tags:
+        - users
+      summary: User registration
+      description: Registers a new user.
+      requestBody:
+        description: Payload for creating a new user.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/createUser'
+        required: true
+      responses:
+        "201":
+          description: The user has been successfully registered. User object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/user'
+        "409":
+          description: A user with this email already exists.
+
+  /v1/users/login:
+    post:
+      tags:
+        - users
+      summary: User authorization
+      description: Authorizes a user based on login and password.
+    get:
+      tags:
+        - users
+      summary: User status check
+      description: Returns information on an authorized user.
+
+  /v1/users/logout:
+    post:
+      tags:
+        - users
+      summary: User logged out
+      description: log out of your account.
+
+  /v1/users/{id}/avatar:
+    post:
+      tags:
+        - users
+      summary: Upload avatar image
+      description: Loads the user's avatar image. Avatar image must be in `png` or `jpg` format.
+
+  /v1/users/{id}/favorite/offers/add:
+    post:
+      tags:
+        - users
+      summary: Add to favorite
+      description: Add to favorite.
+
+  /v1/users/{id}/favorite/offers/delete:
+    post:
+      tags:
+        - users
+      summary: Delete to favorite
+      description: Delete to favorite.
+
+  /v1/offers:
+    post:
+      tags:
+        - offers
+      summary: Create an offer
+      description: Create a new offer.
+      requestBody:
+        description: Payload for creating a new offer.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/offer'
+        required: true
+      responses:
+        "201":
+          description: The offer has been successfully created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/offer'
+        "401":
+          description: Unauthorized.
+
+    get:
+      tags:
+        - offers
+      summary: List offers
+      description: return a list of offers.
+      parameters:
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 60
+          description: Number of returned offers.
+
+  /v1/offers/{userId}:
+    post:
+      tags:
+        - offers
+      summary: Update an offer
+      description: Update an exist offer.
+    get:
+      tags:
+        - offers
+      summary: Detailed offer info
+      description: Get detailed information on the offer.
+    delete:
+      tags:
+        - offers
+      summary: Delete an offer
+      description: Delete an exist offer.
+
+  /v1/offers/{id}/favorite:
+    get:
+      tags:
+        - offers
+      summary: Get favorite offers
+      description: Get favorite offers.
+
+  /v1/offers/premium:
+    get:
+      tags:
+        - offers
+      summary: Premium offers
+      description: Get premium offers.
+      parameters:
+        - in: query
+          name: city
+          schema:
+            type: string
+          description: Name of the city to get premium offers for.
+
+  /v1/comments:
+    get:
+      tags:
+        - comments
+      summary: Get comments
+      description: Get comments.
+
+  /v1/comments/{offerId}:
+    post:
+      tags:
+        - comments
+      summary: Add comment
+      description: Add comment.
+
+components:
+  schemas:
+    createUser:
+      type: object
+      properties:
+        email:
+          type: string
+          example: [email protected]
+        firstname:
+          type: string
+          example: Natalia
+        password:
+          type: string
+          example: 123456
+
+    user:
+      type: object
+      properties:
+        id:
+          type: string
+          example: 6329c3d6a04ab1061c6425ea
+        email:
+          type: string
+          example: [email protected]
+
+    offer:
+      type: object
+      properties:
+        title:
+          type: string
+          example: Houseboat in Amsterdam
+        description:
+          type: string
+          example: Wooden cabin with sea view located in the Danish nature.
+        postDate:
+          type: string
+          example: 2024-06-11T06:23:08.406Z
+        city:
+          type: string
+          example: Cologne
+        preview:
+          type: string
+          example: preview.jpg
+        photos:
+          type: array
+          example: ['photo1.jpg', 'photo2.jpg']
+        isPremium:
+          type: boolean
+          example: true
+        isFavorite:
+          type: boolean
+          example: true
+        rating:
+          type: number
+          example: 4.8
+        type:
+          type: string
+          example: house
+        roomsCount:
+          type: number
+          example: 1
+        guestsCount:
+          type: number
+          example: 2
+        price:
+          type: number
+          example: 10500
+        amenities:
+          type: array
+          example: ['seat', 'Washer', 'Towels']
+        userId:
+          type: string
+          example: 6329c3d6a04ab1061c6425ea
+        latitude:
+          type: number
+          example: 50.938361
+        longitude:
+          type: number
+          example: 6.959974