openapi.yaml

openapi: 3.0.0
info:
  description: |
    厦门大学 *2017~18上* **面向对象分析与设计** 课堂管理系统 `RESTful API` 标准
  version: "1.0.0-beta.3"
  title: 课堂管理系统
  contact:
    url: 'https://github.com/Librazy/ControllerWorkingGroup-Public'
tags:
  - name: me
    description: 用户个人信息
  - name: course
    description: 课程信息
  - name: class
    description: 班级信息
  - name: seminar
    description: 讨论课信息
  - name: topic
    description: 话题信息
  - name: group
    description: 分组信息
paths:
  '/me':
    get:
      tags:
        - me
      summary: 获取当前用户
      operationId: getCurrentUser
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/User'
                - required:
                  - id
                  - type
                  - name
                  - number
                  - phone
                  - email
                  - gender
                  - school
                  - title
                  - avatar
                - properties:
                    school:
                      allOf:
                      - $ref: '#/components/schemas/School'
                      - required:
                        - id
                        - name
                example: {"id": 3486, "type": "student", "name": "张三", "number": "23320152202333", "phone": "18911114514", "email": "23320152202333@stu.xmu.edu.cn", "gender": "male", "school": {"id": 32, "name": "厦门大学"}, "title": "", "avatar": "/avatar/3486.png"}
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    put:
      tags:
        - me
      summary: 修改当前用户
      description: .Net 解绑为置空 `phone`，J2EE 解绑为置空 `unionId`
      operationId: updateCurrentUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
                allOf:
                - $ref: '#/components/schemas/User'
                example: {"name": "张三", "number": "23320152202333", "email": "23320152202333@stu.xmu.edu.cn", "gender": "female", "title": "", "avatar": "/avatar/3486.png"}
      responses:
        '204':
          description: 成功
        '400':
          description: 信息不合法（邮箱格式错误、学校不存在、头像不存在、在设置了`type`后重新设置等）
      security:
        - wechat_auth:
          - 'snsapi_login'
        - http_pwd: []
        - mp_code: []
  '/signin':
    get:
      tags: 
      - me
      summary: 微信小程序/OAuth2登录
      description: |
        `state` 为 `MiniProgram` 时返回 `text/html` (作为微信登录的 `redirect_uri`），否则返回 `application/json` (作为小程序上传 Code 的接口）。  
        **若该微信用户是第一次登录，则后台执行注册流程并返回新生成的用户。**
      operationId: signinWechat
      parameters:
      - name: code
        in: query
        description: 微信小程序/OAuth2授权的Code
        schema:
          type: string
      - name: state
        in: query
        required: true
        description: 微信OAuth2授权的state。对于小程序，值恒为 `MiniProgram`
        schema:
          type: string
      - name: success_url
        in: query
        description: 微信OAuth2授权后跳转到的网址
        schema:
          type: string
          format: url
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/User'
                - required:
                  - id
                  - type
                  - jwt
                - properties:
                    jwt: 
                      type: string
                      format: password
                      description: Json Web Token， 用于维护用户登录状态，接收后小程序使用 `wx.setStorage` 存储
                  example: {"id": 3486, "type": "student", "name": "张三", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjaWQiOiJPQTAwMDEiLCJpYXQiOjE0ODI2NTcyODQyMjF9.TeJpy936w610Vrrm+c3+RXouCA9k1AX0Bk8qURkYkdo="}
            text/html:
              schema:
                allOf:
                - $ref: '#/components/schemas/User'
                - required:
                  - id
                  - type
                  - name
                  - jwt
                - properties:
                    jwt: 
                      type: string
                      format: password
                - description: Json Web Token，用于维护用户登录状态，接收后小程序使用 `wx.setStorage` 存储
                  example: |
                    <!doctype html><html lang=zh><head><meta charset=utf-8><title>blah</title><script>window.localStorage.setItem("user", '{"id": 3486, "type": "student", "name": "张三", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjaWQiOiJPQTAwMDEiLCJpYXQiOjE0ODI2NTcyODQyMjF9.TeJpy936w610Vrrm+c3+RXouCA9k1AX0Bk8qURkYkdo="}');window.location.href="/";</script></head></html>
        '401':
          description: 登录失败。对小程序返回 401 的通用JSON，对网页微信登录返回一个 401 错误页HTML。
    post:
      tags:
      - me
      summary: .Net 手机号密码登录
      operationId: signinPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                phone:
                  type: string
                password:
                  type: string
                  format: password
              required:
              - phone
              - password
              example: {"phone": "18911114514", "password": "qwer2345!"}
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/User'
                - required:
                  - id
                  - type
                  - name
                  - jwt
                - properties:
                    jwt: 
                      type: string
                      format: password
                      description: Json Web Token， 用于维护用户登录状态，接收后存储于 `localStorage` （对应小程序 `wx.setStorage`）
                  example: {"id": 3486, "type": "student", "name": "张三", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjaWQiOiJPQTAwMDEiLCJpYXQiOjE0ODI2NTcyODQyMjF9.TeJpy936w610Vrrm+c3+RXouCA9k1AX0Bk8qURkYkdo="}
        '401':
          description: 手机号密码错误
  '/register':
    post:
      tags:
      - me
      summary: .Net 手机号密码注册
      operationId: registerPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                phone:
                  type: string
                password:
                  type: string
                  format: password
              required:
              - phone
              - password
              example: {"phone": "18911114514", "password": "qwer2345!"}
      responses:
        '200':
          description: 注册成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/User'
                - required:
                  - id
                  - type
                  - name
                  - jwt
                - properties:
                    jwt: 
                      type: string
                      format: password
                      description: Json Web Token，用于维护用户登录状态，接收后小程序使用 `wx.setStorage` 存储
                  example: {"id": 3486, "type": "unbinded", "name": "", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjaWQiOiJPQTAwMDEiLCJpYXQiOjE0ODI2NTcyODQyMjF9.TeJpy936w610Vrrm+c3+RXouCA9k1AX0Bk8qURkYkdo="}
  '/school?city={city}':
    get:
      tags:
        - school
      summary: 获取学校列表（按照城市查找学校）
      operationId: getSchools
      parameters:
      - name: city
        in: query
        required: true
        description: 学校的城市
        schema:
          type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/School'
                  - required:
                    - id
                    - name
                    - province
                    - city
                example: [{"id": 32, "name": "厦门大学", "province": "福建", "city": "厦门"}, {"id": 37, "name": "厦门软件学院", "province": "福建", "city": "厦门"},]
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/school':
    post:
      tags:
        - school
      summary: 添加学校
      operationId: createSchool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/School'
              - required:
                - name
                - province
                - city
              example: {"name": "厦门市人民公园", "province": "福建", "city": "厦门"}
      responses:
        '201':
          description: 创建成功，返回学校的ID
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/School'
                - required:
                  - id
                example: {"id": 38}
        '409':
          description: 与其他学校重复（在同地区由重名学校）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/school/province':
    get:
      tags:
        - school
      summary: 获取省份列表
      operationId: getProvinces
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  type: string
                example: ["北京", "天津", "河北省", "……", "澳门特别行政区"]
  '/school/city?province={province}':
    get:
      tags:
        - school
      summary: 获取城市列表
      operationId: getCities
      parameters:
      - name: province
        in: query
        required: true
        description: 省份
        schema:
          type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  type: string
                example: ["北京", "天津", "河北省", "……", "澳门特别行政区"]
        '404':
          description: 找不到这个省份
  '/course':
    get:
      tags:
        - course
      summary: 获取与当前用户相关联的课程列表
      operationId: getUserCourses
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Course'
                  - required:
                    - id
                    - name
                    - numClass
                    - numStudent
                    - startTime
                    - endTime
                example: [{"id": 1, "name": "OOAD", "numClass": 3, "numStudent": 60, "startTime": "2017-9-1", "endTime": "2018-1-1"},  {"id": 2, "name": "J2EE", "numClass": 1, "numStudent": 60, "startTime": "2017-9-1", "endTime": "2018-1-1"}]
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    post:
      tags:
        - course
      summary: 创建课程
      operationId: createCourse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Course'
              - required:
                - name
                - proportions
                - startTime
                - endTime
              example: {"name": "OOAD", "description": "面向对象分析与设计", "startTime": "2017-09-20", "endTime": "2018-1-31", "proportions": {"report": 50, "presentation": 50, "c": 20, "b": 60, "a": 20 }}
      responses:
        '201':
          description: 创建成功，返回课程的ID
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Course'
                - required:
                  - id
                example: {"id": 23}
        '403':
          description: 用户权限不足（学生无法创建课程）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/course/{courseId}':
    get:
      tags:
        - course
      summary: 按ID获取课程
      operationId: getCourseById
      parameters:
      - name: courseId
        in: path
        description: 需获取课程的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CourseDetail'
                - required:
                  - id
                  - name
                  - description
                  - teacherName
                  - teacherEmail
                example: {"id": 23, "name": "OOAD", "description": "面向对象分析与设计", "teacherName": "邱明", "teacherEmail": "mingqiu@xmu.edu.cn"}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到课程
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    put:
      tags:
        - course
      summary: 修改课程
      operationId: updateCourse
      parameters:
      - name: courseId
        in: path
        description: 需修改课程的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Course'
              - example: {"name": "OOAD", "description": "面向对象分析与设计", "startTime": "2017-09-20", "endTime": "2018-1-1", "proportions": {"report": 70, "presentation": 30, "c": 20, "b": 60, "a": 20 }}
      responses:
        '204':
          description: 修改成功
        '403':
          description: 用户权限不足（学生无法修改课程、无法修改他人课程）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    delete:
      tags:
        - course
      summary: 按ID删除课程
      operationId: deleteCourseById
      parameters:
      - name: courseId
        in: path
        description: 需删除课程的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 用户权限不足（无法删除他人课程、学生无法删除课程）
        '404':
          description: 未找到课程
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/course/{courseId}/class':
    get:
      tags:
        - course
      summary: 按ID获取课程的班级列表
      operationId: getClassesByCourseId
      parameters:
      - name: courseId
        in: path
        description: 需获取班级的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 成功，返回班级的ID和名称
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Class'
                  - required:
                    - id
                    - name  
                example: [{"id": 45, "name": "周三1-2节"}, {"id": 48, "name": "周三3-4节"}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到课程
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    post:
      tags:
        - course
      summary: 在指定ID的课程创建班级
      operationId: createClassByCourseId
      parameters:
      - name: courseId
        in: path
        description: 待创建班级的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Class'
              - required:
                - name
                - site
                - time
                - proportions
              example: {"name": "周三1-2节", "site": "海韵212", "time": "周三一二节", "proportions": {"report": 50, "presentation": 50, "c": 10, "b": 60, "a": 30 }}
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                properties: 
                  id:
                    type: integer
                    format: int64
                    example: 45
        '403':
          description: 用户权限不足（学生无法创建班级）
        '404':
          description: 未找到课程
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class':
    get:
      tags:
        - class
      summary: 获取与当前用户相关的或者符合条件的班级列表
      operationId: getClass
      parameters:
      - name: courseName
        in: query
        description: 课程名称
        schema:
          type: string
      - name: courseTeacher
        in: query
        description: 教师名称
        schema:
          type: string
      responses:
        '200':
          description: 课程班级列表
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/CourseClass'
                  - required:
                    - id
                    - name
                    - time
                    - site
                    - numStudent
                    - courseName
                    - courseTeacher
                example: [{"id": 23, "name": "周三1-2节", "numStudent": 60, "time": "周三1-2、周五1-2", "site": "公寓405", "courseName": "OOAD", "courseTeacher": "邱明"},{"id": 42, "name": "一班", "numStudent": 60, "time": "周三34节 周五12节", "site": "海韵202", "courseName": ".Net 平台开发", "courseTeacher": "杨律青"}]
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}':
    get:
      tags:
        - class
      summary: 按ID获取班级详情
      operationId: getClassById
      parameters:
      - name: classId
        in: path
        description: 需获取班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 班级的详细信息
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Class'
                - required:
                  - id
                  - name
                  - numStudent
                  - calling
                  - time
                  - site
                  - roster
                  - proportions
                - properties:
                    proportions:
                      required:
                      - '3'
                      - '4'
                      - '5'
                      - report
                      - presentation
                example: {"id": 23, "name": "周三1-2节", "numStudent": 120, "time": "周三一二节", "site": "海韵201", "calling": -1, "roster": "/roster/周三12班.xlsx", "proportions": {"report": 50, "presentation": 50, "c": 20, "b": 60, "a": 20 }}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    put:
      tags:
        - class
      summary: 按ID修改班级
      description: 可以用于修改签到状态或其他班级信息
      operationId: updateClassById
      parameters:
      - name: classId
        in: path
        description: 需获取班级的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Class'
              - required:
                - name
                - numStudent
                - calling
                - timeSite
                - roster
                - proportions
              - properties:
                  proportions:
                    required:
                    - C
                    - B
                    - A
                    - report
                    - presentation
                example: {"name": "周三1-2节", "numStudent": 120, "time":"周三12节 周一34节", "site": "海韵201，公寓405", "calling": -1, "roster": "/roster/周三12班.xlsx", "proportions": {"report": 50, "presentation": 50, "c": 20, "b": 60, "a": 20 }}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、班级名单不存在
        '403':
          description: 用户权限不足（无法修改他人班级、学生无法修改班级）
        '404':
          description: 未找到班级
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    delete:
      tags:
        - class
      summary: 按ID删除班级
      operationId: deleteClassById
      parameters:
      - name: classId
        in: path
        description: 需删除班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 用户权限不足（无法删除他人班级、学生无法删除班级）
        '404':
          description: 未找到班级
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/student':
    get:
      tags:
        - class
      summary: 按班级ID查找学生列表（查询学号、姓名开头）
      operationId: selectClass
      parameters:
      - name: classId
        in: path
        description: 学生所属的班级ID
        required: true
        schema:
          type: integer
          format: int64
      - name: numBeginWith
        in: query
        description: 学生的学号开头
        schema:
          type: string
      - name: nameBeginWith
        in: query
        description: 学生的姓名开头
        schema:
          type: string
      responses:
        '200':
          description: 满足条件的学生列表
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Student'
                  - required:
                    - id
                    - name
                example: [{"id": 233, "name": "张三", "number": 24320152202333}, {"id": 245, "name": "张八", "number": 24320152202334}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    post:
      tags:
        - class
      summary: 学生按ID选择班级
      operationId: selectClass
      parameters:
      - name: classId
        in: path
        description: 待选择的班级ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 233}
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                properties: 
                  url:
                    type: string
                    format: url
                    example: "/class/34/student/2757"
        '400':
          description: 错误的ID格式
        '403':
          description: 学生无法为他人选课（请求体中ID与自身ID不同）
        '409':
          description: 已选过同课程的课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/student/{studentId}':
    delete:
      tags:
        - class
      summary: 学生按ID取消选择班级
      operationId: deselectClass
      parameters:
      - name: classId
        in: path
        description: 取消选择的班级的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: studentId
        in: path
        description: 学生ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 学生无法为他人退课（URL中ID与自身ID不同）
        '404':
          description: 不存在这个选课或不存在这个学生、班级
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/classgroup':
    get:
      tags:
        - class
      summary: 按ID获取自身所在班级小组
      operationId: getClassGroupByClassId
      parameters:
      - name: classId
        in: path
        description: 班级小组所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 包含自身的班级小组（默认为自己是组长）
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ClassGroup'
                - required:
                  - leader
                  - members
                - properties:
                    leader:
                      allOf:
                      - $ref: '#/components/schemas/Student'
                      - required:
                        - id
                        - name
                        - number
                    members:
                      type: array
                      uniqueItems: true
                      items:
                        allOf:
                        - $ref: '#/components/schemas/Student'
                        - required:
                          - id
                          - name
                          - number
                  example: {"leader": {"id": 2757, "name": "张三", "number": "23320152202333"}, "members": [{"id": 2756, "name": "李四", "number": "23320152202443"}, {"id": 2777, "name": "王五", "number": "23320152202433"}]}
        '400':
          description: 错误的ID格式
        '403':
          description: 教师访问此API
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/classgroup/resign':
    put:
      tags:
      - class
      summary: 班级小组组长辞职
      operationId: resignClassGroupLeader
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、辞职的学生不存在
        '403':
          description: 权限不足（不是该小组的组长）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/classgroup/assign':
    put:
      tags:
      - class
      summary: 成为班级小组组长
      operationId: assignClassGroupLeader
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、成为组长的学生不存在
        '403':
          description: 权限不足（不是该小组的成员）
        '409':
          description: 已经有组长了
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/classgroup/add':
    put:
      tags:
      - class
      summary: 添加班级小组成员
      operationId: addClassGroupMember
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、待添加的学生不存在
        '403':
          description: 权限不足（不是该小组的成员）
        '409':
          description: 待添加学生已经在小组里了
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/class/{classId}/classgroup/remove':
    put:
      tags:
      - class
      summary: 移除成员
      operationId: removeClassGroupMember
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、待移除的学生不存在
        '403':
          description: 权限不足（不是该小组的成员/组长）
        '409':
          description: 待移除学生不在小组里
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/course/{courseId}/seminar':
    get:
      tags:
        - course
      summary: 按课程ID获取讨论课详情列表
      description: 学生可以设置 `?embedGrade=true` 查看分数 `grade`，默认 `embedGrade=false` JSON中则不包含 `grade`
      operationId: getSeminarsByCourseId
      parameters:
      - name: courseId
        in: path
        description: 需获取讨论课的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: embedGrade
        in: query
        description: 是否包含分数（学生小程序需要）
        schema:
          type: boolean
      responses:
        '200':
          description: 讨论课的详情列表
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Seminar'
                  - required:
                    - id
                    - name
                    - description
                    - groupingMethod
                    - startTime
                    - endTime
                  - properties:
                      grade:
                        type: integer
                        minimum: 1
                        maximum: 5
                example: [{"id": 29, "name": "界面原型设计", "description": "界面原型设计", "groupingMethod": "fixed", "startTime": "2017-09-25", "endTime": "2017-10-09", "grade": 4}, {"id": 32, "name": "概要设计", "description": "模型层与数据库设计", "groupingMethod": "fixed", "startTime": "2017-10-10", "endTime": "2017-10-24", "grade": 5}]
        '400':
          description: 错误的ID格式、教师设置embedGrade为true
        '404':
          description: 未找到课程
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    post:
      tags:
        - course
      summary: 在指定ID的课程创建讨论课
      operationId: createSeminarByCourseId
      parameters:
      - name: courseId
        in: path
        description: 待创建讨论课的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Seminar'
              - required:
                - name
                - description
                - groupingMethod
                - startTime
                - endTime
                - proportions
              example: {"name": "概要设计", "description": "模型层与数据库设计", "groupingMethod": "fixed", "startTime": "2017-10-10", "endTime": "2017-10-24", "proportions": {"report": 50, "presentation": 50, "c": 20, "b": 60, "a": 20 }}
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                properties: 
                  id:
                    type: integer
                    format: int64
                    example: 32
        '403':
          description: 用户权限不足（学生无法创建）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/course/{courseId}/seminar/current':
    get:
      tags:
        - course
      summary: 获取课程正在进行的讨论课
      operationId: getCurrentSeminarByCourseId
      parameters:
      - name: courseId
        in: path
        description: 需获取讨论课的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 当前讨论课的详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SeminarClasses'
                - required:
                  - id
                  - name
                  - courseName
                  - groupingMethod
                  - startTime
                  - endTime
                  - classes
                example: {"id": 29, "name": "界面原型设计", "courseName": "OOAD", "groupingMethod": "fixed", "startTime": "2017-09-25", "endTime": "2017-10-09", "classes": [{"id": 53, "name": "周三12"}, {"id": 57, "name": "周三34"}]}
        '400':
          description: 错误的ID格式
        '404':
          description: 当前没有正在进行的讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/course/{courseId}/grade':
    get:
      tags:
        - course
      summary: 按课程ID获取学生的所有讨论课成绩
      operationId: getGradesByCourseId
      parameters:
      - name: courseId
        in: path
        description: 需获取讨论课成绩的课程的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 当前讨论课的详情
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SeminarGradeDetail'
                example: [{"seminarName": "需求分析", "groupName": "3A2", "leaderName": "张三", "presentationGrade": 3, "reportGrade": 4, "grade": 4}, {"seminarName": "界面原型设计", "groupName": "3A3", "leaderName": "张三", "presentationGrade": 4, "reportGrade": 4, "grade": 4}]
        '400':
          description: 错误的ID格式
        '404':
          description: 当前没有正在进行的讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课
      operationId: getSeminarById
      parameters:
      - name: seminarId
        in: path
        description: 需获取讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 讨论课详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Seminar'
                - required:
                  - id
                  - name
                  - description
                  - groupingMethod
                  - startTime
                  - endTime
                  - topics
                example: {"id": 32, "name": "概要设计", "description": "模型层与数据库设计", "groupingMethod": "fixed", "startTime": "2017-10-10", "endTime": "2017-10-24", , "topics": [{"id": 257, "name": "领域模型与模块"}]}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    put:
      tags:
        - seminar
      summary: 按ID修改讨论课
      operationId: updateSeminarById
      parameters:
      - name: seminarId
        in: path
        description: 需获取讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Seminar'
              - required:
                - name
                - description
                - groupingMethod
                - startTime
                - endTime
                - proportions
              example: {"name": "概要设计", "description": "模型层与数据库设计", "groupingMethod": "fixed", "startTime": "2017-10-11", "endTime": "2017-10-24", "proportions": {"report": 50, "presentation": 50, "c": 20, "b": 60, "a": 20 }}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    delete:
      tags:
        - seminar
      summary: 按ID删除讨论课
      operationId: deleteSeminarById
      parameters:
      - name: seminarId
        in: path
        description: 需删除讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 权限不足（无法删除他人讨论课、学生无法删除讨论课）
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/my':
    get:
      tags:
        - seminar
      summary: 按ID获取与学生有关的讨论课信息
      operationId: getStudentSeminarById
      parameters:
      - name: seminarId
        in: path
        description: 需获取讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 讨论课详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/StudentSeminar'
                - required:
                  - id
                  - name
                  - courseName
                  - groupingMethod
                  - startTime
                  - endTime
                  - classCalling
                  - isLeader
                  - areTopicsSeletced
                example: {"id": 32, "name": "概要设计", "groupingMethod": "random", "courseName": "OOAD", "startTime": "2017-10-11", "endTime": "2017-10-24",  "classCalling": 23, "isLeader": true, "areTopicsSeletced": true}
        '400':
          description: 错误的ID格式、教师请求本API
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/detail':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课详情
      operationId: getSeminarDetailById
      parameters:
      - name: seminarId
        in: path
        description: 需获取讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 讨论课详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SeminarDetail'
                - required:
                  - id
                  - name
                  - site
                  - startTime
                  - endTime
                  - teacherName
                  - teacherEmail
                example: {"id": 32, "name": "概要设计", "startTime": "2017-10-10", "endTime": "2017-10-24", "site": "海韵201", "teacherName": "邱明", "teacherEmail": "mingqiu@xmu.edu.cn"}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/topic':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课的话题
      operationId: getTopicsBySeminarId
      parameters:
      - name: seminarId
        in: path
        description: 需获取话题的讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 话题列表
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Topic'
                  - required:
                    - id
                    - serial
                    - name
                    - description
                    - groupLimit
                    - groupMemberLimit
                    - groupLeft
                example: [{"id": 257, "serial": "A", "name": "领域模型与模块", "description": "Domain model与模块划分", "groupLimit": 5, "groupMemberLimit": 6, "groupLeft": 2}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    post:
      tags:
        - seminar
      summary: 在指定ID的讨论课创建话题
      operationId: createTopicBySeminarId
      parameters:
      - name: seminarId
        in: path
        description: 待创建话题的讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 新增话题
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Topic'
              - required:
                - serial
                - name
                - description
                - groupLimit
                - groupMemberLimit
              example: {"serial": "A", "name": "领域模型与模块", "description": "Domain model与模块划分", "groupLimit": 5, "groupMemberLimit": 6}
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Topic'
                - required:
                  - id
                  example: {"id": 257}
        '403':
          description: 用户权限不足（无法在他人讨论课创建话题、学生无法创建话题）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/group':
    get:
      tags:
        - seminar
      summary: 按讨论课ID查找小组
      operationId: getGroupBySeminarId
      parameters:
      - name: seminarId
        in: path
        description: 需获取讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: gradeable
        in: query
        description: 仅返回当前用户可打分的小组
        schema:
          type: boolean
      - name: classId
        in: query
        description: 仅返回此班级的小组
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 满足条件的小组列表
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  allOf:
                  - $ref: '#/components/schemas/Group'
                  - required:
                    - id
                    - name
                    - topics
                example: [{"id": 28, "name": "1A1", "topics": [{"id": 257, "name": "领域模型与模块"}]}, {"id": 29, "name": "1A2", "topics": [{"id": 257, "name": "领域模型与模块"}]}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/group/my':
    get:
      tags:
        - seminar
      summary: 按讨论课ID获取学生所在小组详情
      operationId: getStudentGroupBySeminarId
      parameters:
      - name: seminarId
        in: path
        description: 讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 小组详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Group'
                - required:
                  - id
                  - name
                  - leader
                  - members
                  - topics
                - properties:
                    leader:
                      allOf:
                      - $ref: '#/components/schemas/Student'
                      - required:
                        - id
                        - number
                        - name
                    members:
                      type: array
                      uniqueItems: true
                      items:
                        allOf:
                        - $ref: '#/components/schemas/Student'
                        - required:
                          - id
                          - number
                          - name
                    topics:
                      type: array
                      uniqueItems: true
                      items:
                        allOf:
                        - $ref: '#/components/schemas/Topic'
                        - required:
                          - id
                          - name
                  example: {"id": 28, "name": 28, "leader": {"id": 8888, "name": "张三"}, "members": [{"id": 5324, "name": "李四"}, {"id": 5678, "name": "王五"}], "topics": [{"id": 257, "name": "领域模型与模块"}]}
        '400':
          description: 错误的ID格式
        '403':
          description: 老师无法使用本API
        '404':
          description: 讨论课尚未分组
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/class/{classId}/attendance':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课班级签到、分组状态
      operationId: getSeminarClassAttendance
      parameters:
      - name: classId
        in: path
        description: 签到状态所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 签到状态
          content:
            application/json:
              schema:
                properties: 
                  className:
                    type: string
                  numPresent:
                    type: integer
                  numStudent:
                    type: integer
                  status:
                    type: string
                    enum:
                    - uncalled
                    - calling
                    - called
                  group:
                    type: string
                    enum:
                    - fixed
                    - grouping
                    - grouped
                required:
                - numPresent
                example: {"numPresent": 40, "numStudent": 60, "status": "calling", "group": "grouping"}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级、讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/class/{classId}/attendance/present':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课班级已签到名单
      operationId: getSeminarClassPresent
      parameters:
      - name: seminarId
        in: path
        description: 签到状态所属讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: classId
        in: path
        description: 签到状态所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 已签到名单
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items: 
                  allOf:
                  - $ref: '#/components/schemas/Student'
                  - required:
                    - id
                    - name
                example: [{"id": 2357, "name": "张三"}, {"id": 8232, "name": "李四"}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级、讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/class/{classId}/attendance/late':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课班级迟到签到名单
      operationId: getSeminarClassLate
      parameters:
      - name: seminarId
        in: path
        description: 签到状态所属讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: classId
        in: path
        description: 签到状态所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 签到状态
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items: 
                  allOf:
                  - $ref: '#/components/schemas/Student'
                  - required:
                    - id
                    - name
                example: [{"id": 3412, "name": "王五"}, {"id": 5234, "name": "王七九"}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级、讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/class/{classId}/attendance/absent':
    get:
      tags:
        - seminar
      summary: 按ID获取讨论课班级缺勤名单
      operationId: getSeminarClassAbsent
      parameters:
      - name: seminarId
        in: path
        description: 签到状态所属讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: classId
        in: path
        description: 签到状态所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 签到状态
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items: 
                  allOf:
                  - $ref: '#/components/schemas/Student'
                  - required:
                    - id
                    - name
                example: [{"id": 34, "name": "张六"}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到班级、讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/seminar/{seminarId}/class/{classId}/attendance/{studentId}':
    put:
      tags:
        - seminar
      summary: 签到(上传位置信息)
      operationId: updateAttendance
      parameters:
      - name: seminarId
        in: path
        description: 签到状态所属讨论课的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: classId
        in: path
        description: 签到状态所属班级的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: studentId
        in: path
        description: 签到状态所属学生的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                longitude:
                  type: number
                  example: 118.1132721
                latitude:
                  type: number
                  example: 24.4307197
                elevation:
                  type: number
                  example: 18.42
              example: {"longitude": 118.1132721, "latitude": 24.4307197, "elevation": 18.42}
      responses:
        '200':
          description: 签到状态，有ontime准点、late迟到两种
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                    enum:
                    - ontime
                    - late
                example: {"status": "late"}
        '400':
          description: 签到失败（位置错误、当前未签到等）
        '403':
          description: 学生无法为他人签到（URL中ID与自身ID不同）
        '404':
          description: 不存在这个学生或班级、讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/topic/{topicId}':
    get:
      tags:
        - topic
      summary: 按ID获取话题
      operationId: getTopicById
      parameters:
      - name: topicId
        in: path
        description: 需获取话题的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 话题详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Topic'
                - required:
                  - id
                  - serial
                  - name
                  - description
                  - groupLimit
                  - groupMemberLimit
                  - groupLeft
                example: {"id": 257, "serial": "A", "name": "领域模型与模块", "description": "Domain model与模块划分", "groupLimit": 5, "groupMemberLimit": 6, "groupLeft": 2}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到话题
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    put:
      tags:
        - topic
      summary: 按ID修改话题
      operationId: updateTopicById
      parameters:
      - name: topicId
        in: path
        description: 需获取话题的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 修改后的话题属性
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Topic'
              - required:
                - name
                - serial
                - description
                - groupLimit
                - groupMemberLimit
              example: {"serial": "A", "name": "领域模型与模块", "description": "Domain model与模块划分", "groupLimit": 6, "groupMemberLimit": 6}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 用户权限不足（无法在他人讨论课修改话题、学生无法修改话题）
        '404':
          description: 未找到话题
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
    delete:
      tags:
        - topic
      summary: 按ID删除话题
      operationId: deleteTopicById
      parameters:
      - name: topicId
        in: path
        description: 需删除话题的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 用户权限不足（无法在他人讨论课修改话题、学生无法修改话题）
        '404':
          description: 未找到话题
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/topic/{topicId}/group':
    get:
      tags:
        - topic
      summary: 按话题ID获取选择了该话题的小组
      operationId: getGroupsByTopicId
      parameters:
      - name: topicId
        in: path
        description: 需获取小组的话题的ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
                example: [{"id": 23}, {"id": 26}]
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到讨论课
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}':
    get:
      tags:
        - group
      summary: 按小组ID获取小组详情
      description: 小组选择的话题和小组的得分可以通过 `GET /group/{groupId}?embedTopics=true&embedGrade=true`获取，但不能通过对应的 `PUT /group/{groupId}` 设置
      operationId: getGroupById
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: embedTopics
        in: query
        description: 是否包含小组选择的话题
        schema:
          type: boolean
      - name: embedGrade
        in: query
        description: 是否包含小组的成绩
        schema:
          type: boolean
      responses:
        '200':
          description: 小组详情
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Group'
                - required:
                  - id
                  - leader
                  - members
                  - topics
                - properties:
                    leader:
                      allOf:
                      - $ref: '#/components/schemas/User'
                      - required:
                        - id
                        - number
                        - name
                      - properties:
                          type:
                            type: string
                            enum: 
                            - student
                    members:
                      type: array
                      uniqueItems: true
                      items:
                        allOf:
                        - $ref: '#/components/schemas/User'
                        - required:
                          - id
                          - number
                          - name
                        - properties:
                            type:
                              type: string
                              enum: 
                              - student
                    topics:
                      type: array
                      uniqueItems: true
                      items:
                        allOf:
                        - $ref: '#/components/schemas/Topic'
                        - required:
                          - id
                          - name
                  example: {"id": 28, "leader": {"id": 8888, "name": "张三"}, "members": [{"id": 5324, "name": "李四"}, {"id": 5678, "name": "王五"}], "topics": [{"id": 257, "name": "领域模型与模块"}], "report": ""}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到小组
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/resign':
    put:
      tags:
      - group
      summary: 组长辞职
      operationId: resignGroupLeader
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、辞职的学生不存在
        '403':
          description: 权限不足（不是该小组的组长）
        '404':
          description: 小组不存在
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/assign':
    put:
      tags:
      - group
      summary: 成为组长
      operationId: assignGroupLeader
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、成为组长的学生不存在
        '403':
          description: 权限不足（不是该小组的成员）
        '404':
          description: 小组不存在
        '409':
          description: 已经有组长了
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/add':
    put:
      tags:
      - group
      summary: 添加成员
      operationId: addGroupMember
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、待添加的学生不存在
        '403':
          description: 权限不足（不是该小组的成员）
        '404':
          description: 小组不存在
        '409':
          description: 待添加学生已经在小组里了
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/remove':
    put:
      tags:
      - group
      summary: 移除成员
      operationId: removeGroupMember
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 学生的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Student'
              - required:
                - id
              example: {"id": 247}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、待移除的学生不存在
        '403':
          description: 权限不足（不是该小组的成员/组长）
        '404':
          description: 小组不存在
        '409':
          description: 待移除学生不在小组里
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/topic':
    post:
      tags:
        - group
      summary: 小组按ID选择话题
      operationId: selectTopic
      parameters:
      - name: groupId
        in: path
        description: 小组的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        description: 话题的ID
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Topic'
              - required:
                - id
              example: {"id": 23}
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                properties: 
                  url:
                    type: string
                    format: url
                    example: "/group/27/topic/23"
        '400':
          description: 错误的ID格式或话题已满
        '403':
          description: 权限不足（不是该小组的组长）
        '404':
          description: 小组不存在
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/topic/{topicId}':
    delete:
      tags:
        - group
      summary: 小组按ID取消选择话题
      operationId: deselectTopic
      parameters:
      - name: topicId
        in: path
        description: 取消选择的话题的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: groupId
        in: path
        description: 小组ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到话题选择
        '403':
          description: 权限不足（不是该小组的组长）
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/grade':
    get:
      tags:
        - group
      summary: 按ID获取小组的讨论课成绩
      operationId: getGradeByGroupId
      parameters:
      - name: groupId
        in: path
        description: 需获取成绩的小组ID
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SeminarGrade'
                - example: {"presentationGrade": [{"topicId": 257, "grade": 4}, {"topicId": 258, "grade": 5}], "reportGrade": 3, "grade": 4}
        '400':
          description: 错误的ID格式
        '404':
          description: 未找到小组
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/grade/report':
    put:
      tags:
        - group
      summary: 按ID设置小组的报告分
      operationId: finalGradeByGroupId
      parameters:
      - name: groupId
        in: path
        description: 需设置成绩的小组ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                reportGrade:
                  type: integer
                  format: char
                  minimum: 1
                  maximum: 5
              example: {"reportGrade": 5}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式
        '403':
          description: 权限不足（学生无法设置成绩、无法修改他人班级的小组）
        '404':
          description: 未找到小组
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/group/{groupId}/grade/presentation/{studentId}':
    put:
      tags:
        - group
      summary: 提交对其他小组的打分
      operationId: submitGradeByGroupId
      parameters:
      - name: groupId
        in: path
        description: 被打分的小组的ID
        required: true
        schema:
          type: integer
          format: int64
      - name: studentId
        in: path
        description: 打分的学生的ID
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                presentationGrade:
                  type: array
                  items:
                    properties:
                      topicId:
                        type: integer
                        format: int64
                      grade:
                        type: integer
                        format: char
                        minimum: 1
                        maximum: 5
              example: {"presentationGrade": [{"topicId": 257, "grade": 4}, {"topicId": 258, "grade": 5}]}
      responses:
        '204':
          description: 成功
        '400':
          description: 错误的ID格式、对无权评分的小组评分
        '404':
          description: 未找到小组
        '409':
          description: 已评分，不能重复评分
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
  '/upload/avatar':
    post:
      tags: 
      - upload
      summary: 上传头像
      operationId: uploadAvatar
      requestBody:
        required: true
        content:
          'multipart/form-data':
              schema:
                properties:
                  file:
                    type: string
                    format: binary
      responses:
        '201':
          description: 服务器上的头像文件URL
          content:
            application/json:
              schema:
                properties: 
                  url:
                    type: string
                    format: url
                    example: "/avatar/3486.png"
        '400':
          description: 图片大小不符合要求、图片格式不正确、不是有效的图片
      security:
        - http_pwd: []
        - mp_code: []
        - wechat_auth: 
          - snsapi_login
externalDocs:
  description: 更多信息
  url: 'https://github.com/Librazy/ControllerWorkingGroup-Public'
components:
  securitySchemes:
    http_pwd:
      description: 密码登录，JWT 或 Session Cookie 鉴权
      type: http
      scheme: bearer
      bearerFormat: JWT
    wechat_auth:
      type: oauth2
      description: 微信扫码Oauth2登录，JWT 或 Session Cookie 鉴权
      flows: 
        authorizationCode:
          authorizationUrl: https://open.weixin.qq.com/connect/qrconnect
          tokenUrl: https://api.weixin.qq.com/sns/oauth2/access_token
          scopes:
            snsapi_login: 微信登录
    mp_code:
      type: apiKey
      name: code
      description: 小程序登录，JWT 或 Session Cookie 鉴权
      in: query
  schemas:
    User:
      type: object
      properties:
        id:
          description: 用户的唯一ID
          type: integer
          format: int64
          readOnly: true
        type:
          type: string
          description: 用户的类型
          readOnly: true
          enum:
          - student
          - teacher
        number:
          description: 用户的学号/教工号
          type: string
        name:
          description: 用户的姓名
          type: string
        phone:
          description: 用户的电话号码
          type: string
        email:
          description: 用户的Email
          type: string
        gender:
          type: string
          description: 用户的性别
          enum:
            - male
            - female
        school:
          description: 用户的学校
          readOnly: true
          $ref: '#/components/schemas/School'
        title:
          description: 用户的头衔
          type: string
        password:
          description: 用户的密码
          type: string
          format: password
          writeOnly: true
        unionId:
          description: 用户的微信UnionID
          type: string
          format: password
          writeOnly: true
        avatar:
          description: 用户的头像
          type: string
          format: url
      additionalProperties: false
    Student:
      allOf:
      - $ref: '#/components/schemas/User'
      - properties:
          type:
            type: string
            enum: 
            - student
    Teacher:
      allOf:
      - $ref: '#/components/schemas/User'
      - properties:
          type:
            type: string
            enum: 
            - teacher
    Class: 
      type: object
      properties:
        id:
          description: 班级的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 班级的名称
          type: string
        numStudent:
          description: 班级的人数
          type: integer
        time:
          description: 班级的上课时间 
          type: string
        site:
          description: 班级的上课地点 
          type: string
        calling:
          description: 班级正在签到的讨论课ID, -1 表示当前未签到
          type: integer
          format: int64
        roster:
          description: 班级学生名单
          type: string
          format: url
        proportions:
          type: object
          properties:
            report:
              type: integer
              minimum: 0
              maximum: 100
            presentation:
              type: integer
              minimum: 0
              maximum: 100
            c: 
              type: integer
              minimum: 0
              maximum: 100
            b: 
              type: integer
              minimum: 0
              maximum: 100
            a: 
              type: integer
              minimum: 0
              maximum: 100
    CourseClass:
      type: object
      properties:
        id:
          description: 班级的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 班级的名称
          type: string
        numStudent:
          description: 班级的人数
          type: integer
        time:
          description: 班级的上课时间 
          type: string
        site:
          description: 班级的上课地点 
          type: string
        courseName:
          description: 课程的名称
          type: string
        courseTeacher:
          $ref: '#/components/schemas/Teacher'
    Course:
      type: object
      properties:
        id:
          description: 课程的唯一ID
          type: integer
          format: int64
          readOnly: true
        teacher:
          $ref: '#/components/schemas/Teacher'
        name:
          description: 课程的名称
          type: string
        numClass:
          readOnly: true
          description: 班级数量
          type: integer
        numStudent:
          readOnly: true
          description: 学生数量
          type: integer
        startTime:
          description: 课程开始时间
          type: string
          format: date
        endTime:
          description: 课程结束时间
          type: string
          format: date
        description:
          description: 课程描述
          type: string
        proportions:
          type: object
          properties:
            report:
              type: integer
              minimum: 0
              maximum: 100
            presentation:
              type: integer
              minimum: 0
              maximum: 100
            c: 
              type: integer
              minimum: 0
              maximum: 100
            b: 
              type: integer
              minimum: 0
              maximum: 100
            a: 
              type: integer
              minimum: 0
              maximum: 100
      additionalProperties: false
    CourseDetail:
      type: object
      properties:
        id:
          description: 课程的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 课程的名称
          type: string
        description:
          description: 课程描述
          type: string
        teacherName:
          description: 课程教师的名称
          type: string
        teacherEmail:
          description: 课程教师的email
          type: string
          format: email
      additionalProperties: false
    Seminar:
      type: object
      properties:
        id:
          description: 讨论课的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 讨论课的名称
          type: string
        description:
          description: 讨论课描述
          type: string
        groupingMethod:
          description: 讨论课分组方式
          type: string
          enum:
            - random
            - fixed
        startTime:
          description: 讨论课开始时间
          type: string
          format: date
        endTime:
          description: 讨论课结束时间
          type: string
          format: date
        topics:
          type: array
          description: 讨论课的话题列表
          readOnly: true
          items:
            allOf:
            - $ref: '#/components/schemas/Topic'
            - required:
              - id
              - name
        proportions:
          type: object
          properties:
            report:
              type: integer
              minimum: 0
              maximum: 100
            presentation:
              type: integer
              minimum: 0
              maximum: 100
            c: 
              type: integer
              minimum: 0
              maximum: 100
            b: 
              type: integer
              minimum: 0
              maximum: 100
            a: 
              type: integer
              minimum: 0
              maximum: 100
      additionalProperties: false
    SeminarDetail:
      type: object
      properties:
        id:
          description: 讨论课的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 讨论课的名称
          type: string
        site:
          description: 讨论课班级的地点
          type: string
        startTime:
          description: 讨论课开始时间
          type: string
          format: date
        endTime:
          description: 讨论课结束时间
          type: string
          format: date
        teacherName:
          description: 讨论课教师的名称
          type: string
        teacherEmail:
          description: 讨论课教师的email
          type: string
          format: email
      additionalProperties: false
    SeminarClasses:
      type: object
      properties:
        id:
          description: 讨论课的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 讨论课的名称
          type: string
        courseName:
          description: 课程的名称
          type: string
        startTime:
          description: 讨论课开始时间
          type: string
          format: date
        endTime:
          description: 讨论课结束时间
          type: string
          format: date
        classes:
          description: 课程的班级列表
          type: array
          items:
            type: object
            properties:
              id:
                description: 班级的唯一ID
                type: integer
                format: int64
              name:
                description: 班级的名称
                type: integer
                format: int64
      additionalProperties: false
    StudentSeminar:
      type: object
      properties:
        id:
          description: 讨论课的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 讨论课的名称
          type: string
        groupingMethod:
          description: 讨论课分组方式
          type: string
          enum:
            - random
            - fixed
        courseName:
          description: 课程的名称
          type: string
        startTime:
          description: 讨论课开始时间
          type: string
          format: date
        endTime:
          description: 讨论课结束时间
          type: string
          format: date
        classCalling:
          description: 学生所在班级是否正在签到（-1为否，{classId}为是）
          type: integer
          format: int64
        isLeader:
          description: 学生是否为组长
          type: boolean
        areTopicsSeletced:
          description: 是否完成选题
          type: boolean
    SeminarGrade:
      type: object
      properties:
        presentationGrade:
          description: 展示得分
          type: array
          items: 
            properties:
              topicId: 
                description: 分数所属话题的ID
                type: integer
                format: int64
              grade:
                description: 本话题展示得分
                type: integer
                format: char
                minimum: 1
                maximum: 5
        reportGrade:
          description: 报告得分
          type: integer
          format: char
          minimum: 1
          maximum: 5
        grade:
          description: 最终得分
          type: integer
          readOnly: true
          format: char
          minimum: 1
          maximum: 5
      additionalProperties: false
    SeminarGradeDetail:
      type: object
      properties:
        groupName:
          description: 小组名称
          type: string
        leaderName:
          description: 组长名称
          type: string
        presentationGrade:
          description: 展示得分
          type: integer
          format: char
          minimum: 1
          maximum: 5
        reportGrade:
          description: 报告得分
          type: integer
          format: char
          minimum: 1
          maximum: 5
        grade:
          description: 最终得分
          type: integer
          readOnly: true
          format: char
          minimum: 1
          maximum: 5
      additionalProperties: false
    Topic:
      type: object
      properties:
        id:
          description: 话题的唯一ID
          type: integer
          format: int64
          readOnly: true
        serial:
          description: 话题的序号
          type: string
        name:
          description: 话题的名称
          type: string
        description:
          description: 话题描述
          type: string
        groupLimit:
          description: 组数限制
          type: integer
        groupMemberLimit:
          description: 小组人数限制
          type: integer
        groupLeft:
          description: 组数剩余
          type: integer
          readOnly: true
    ClassGroup:
      type: object
      properties:
        leader:
          description: 队长
          allOf:
          - $ref: '#/components/schemas/User'
          - properties:
              type:
                type: string
                enum: 
                - student
        members:
          description: 队员
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/User'
            - required:
              - id
              properties:
                type:
                  type: string
                  enum: 
                  - student
    Group:
      type: object
      properties:
        id:
          type: string
          description: 小组的唯一ID
          readOnly: true
        name:
          type: string
          description: 小组的名称
          readOnly: true
        leader:
          description: 队长
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/User'
          - properties:
              type:
                type: string
                enum: 
                - student
        members:
          description: 队员
          type: array
          readOnly: true
          uniqueItems: true
          items:
            allOf:
            - $ref: '#/components/schemas/User'
            - required:
              - id
              properties:
                type:
                  type: string
                  enum: 
                  - student
        topics:
          type: array
          description: 小组的选题状况
          readOnly: true
          items:
            allOf:
            - $ref: '#/components/schemas/Topic'
            - required:
              - id
              - name
        report:
          type: string
          readOnly: true
          description: 小组的报告
          format: url
        grade:
          readOnly: true
          $ref: '#/components/schemas/SeminarGrade'
    School:
      type: object
      properties:
        id:
          description: 学校的唯一ID
          type: integer
          format: int64
          readOnly: true
        name:
          description: 学校的名称
          type: string
        province:
          description: 学校的省、直辖市、自治区、特别行政区
          type: string
        city:
          description: 学校的市、区、县
          type: string