Swagger: создать API - PullRequest
Новая
       44

Swagger: создать API

0 голосов
/ 20 марта 2020

Я совершенно новичок в чванстве и веб-сервисах в целом. Но теперь я хотел бы попробовать простой пример и мне нужна помощь:

Я хотел бы создать веб-сервис, где я получу доступные курсы в университете данного семестра:

Так что мой ввод будет выглядеть примерно так: 

{   
  "Study-Program":"Electrical-Engineering",    
  "Semester":"W2020"     
}

и мой вывод 

{   
"Study-Program":"Electrical-Engineering",   
"Semester":"W2020",   
"Courses": [  
{  
"name": "Course1",   
 "type":"type1",  
 "ects":4,  
 "courseID":123456   
},    
{  
"name": "Course2",   
 "type":"type2",  
 "ects":5,  
 "courseID":123457   
},    
   ]    
}

Теперь я попытался указать это в чванстве и хотел спросить, правильно ли я это сделал ...

Сначала я установил пути и определил POST-команду для добавления нового курса, затем GET-команду, чтобы получить желаемый результат.
Теперь мой первый вопрос: В swagger я просто определяю что я ожидаю в качестве входа и выхода правильно? Но логика c, стоящая за командой, должна быть сделана позже, например, в python flask, когда я загружаю заглушку сервера? 

paths:
  /course:
    post: 
      tags:
      - "course"
      summary: "Add a new course"
      operationId: "addCourse"
      consumes: 
      - "application/json"
      produces: 
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Course object that needs to be added to the store"
        schema:
          $ref: '#/definitions/course'
      responses:
        200:
          description:
            "Course added"
          schema: 
            $ref: '#/definitions/course'
        405: 
          description: "Invalid input"

  /course/findBySemester:
    get: 
      tags: 
      - "course"
      summary: "Find course by study-program"
      operationId: "findCourseBySemester"
      produces: 
      - "application/json"
      parameters:
      - name: "study-program"
        in: "query"
        description: "Study-program that needs to be considered for filter"
        type: "array"
        items: 
          type: "string"
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/output'
        400:
          description: Invalid study-program

Затем мне нужно определить определения мои объекты. Могу ли я сделать это так? Потому что я не совсем уверен насчет ссылок и списка в выходных данных ... 

definitions:
  course: 
    type: "object"
    properties:
      study-program: 
        $ref: '#/definitions/study-program'
      name:
        $ref: '#/definitions/name'
      courseID:
        $ref: '#/definitions/courseID'
      ECTS: 
        $ref: '#/definitions/ECTS'
      type: 
        $ref: '#/definitions/type'
      semester:
        $ref: '#/definitions/semester'
  outputCourse: 
    type: "object"
    properties:
      name:
        $ref: '#/definitions/name'
      type: 
        $ref: '#/definitions/type'
      ECTS: 
        $ref: '#/definitions/ECTS'
      courseID:
        $ref: '#/definitions/courseID'
  output: 
    type: "object"
    properties:
      study-program: 
        $ref: '#/definitions/study-program'
      semester:
        $ref: '#/definitions/semester'
      courseList: 
        type: "array"
        items: 
          $ref: '#/definitions/outputCourse'
  name:
        type: "string"
        example: "Adaptive-Systems"
  ECTS: 
        type: "integer"
        format: "int64"
  type: 
        type: "string"
        example: "VO"
  courseID:
        type: "integer"
        format: "int64"
  study-program: 
        type: "string"
        example: "Electrical-Engineering"
  semester:
        type: "string"
        example: "WS19"

Буду признателен за любую помощь, так как я действительно новичок в этой теме! Спасибо!

...