Ինչպե՞ս է տեսք ունենում ձեր արհեստագործությունը REST պայմանագրի նկարագրության ժամանակ։

REST պայմանագրի նկարագրության համար արտեֆակտը սովորաբար ներկայացնում է փաստաթուղթ կամ ֆայլերի հավաքածու, որոնցում ֆորմալիզացված է API-ի նկարագիրը՝ դրա վերջնակետերը, մեթոդները, պարամետրերը, հարցումների և պատասխանների ձևաչափերը, սխալի կոդերը և այլն:

Ամենաշատ օգտագործվողը OpenAPI (նախկինում Swagger) մասնագիտացումն է, որը թույլ է տալիս կառուցվածքային նկարագրություն տալ REST API-ի YAML կամ JSON ձևաչափով: Այս փաստաթուղթը ծառայում է որպես հիմք փաստաթղթավորման, հաճախորդի SDK-ների և թեստերի ստեղծման համար:

OpenAPI-ի կառուցվածքի օրինակ՝

openapi: 3.0.0
info:
  title: Օրինակ API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Ստանալ օգտվողների ցանկը
      responses:
        '200':
          description: Հաջող պատասխան
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Բացի OpenAPI-ից, կարող են օգտագործվել այլ ձևաչափեր կամ պարզ տեքստային փաստաթղթեր պայմանագրերի նկարագրության համար, սակայն OpenAPI-ն ամենատարածվածն է և հարմար է ավտոմատացման համար։