OpenApi-v3 - Swagger 代码示例

openapi: 3.0.0
info:
  description: |
    名称：xxxx API。  
    工具：[swagger](http://swagger.io)  
    规范：[openapi v3.0.0](https://www.openapis.org/)  
  version: "1.8.0"
  title: xxxxxx API Of xxx
  contact:
    email: cloudy.w.h.luo@hsbc.com.cn
  license:
    name: xxxx Privacy (No Public)
    url: 'https://www.xxxx.com.hk/zh-cn'
tags:
  - name: user
    description: 用户信息接口
    externalDocs:
      description: 更详细的API描述，请查看
      url: 'http://xxxxx'
paths:
  /api/ad/getinfo:
    get:
      tags:
        - user
      summary: AD验证，成功则返回用户信息
      operationId: getUserGroupById
      parameters:
        - name: appid
          in: query
          description: APP 的 ID.
          required: true
          schema:
            type: string
        - name: adaccount
          in: query
          description: AD 账号.
          required: true
          schema:
            type: string
        - name: adpassword
          in: query
          description: AD 密码.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: AD验证成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 参数错误
        '401':
          description: 无权限（APP）
        '403':
          description: 无权限（AD用户）
        '404':
          description: 账号或密码错误
  '/api/ad/queryuser/{adaccount}':
    get:
      tags:
        - user
      summary: 获取某个用户的详细信息
      description: 获取某个用户的详细信息
      operationId: getUserDetailById
      parameters:
        - name: adaccount
          in: path
          description: AD 账号.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid username supplied
        '404':
          description: User not found
  '/api/ad/updateuser/{adaccount}':
    put:
      tags:
        - user
      summary: 修改某个用户的信息
      description: 需要验证授权码后才能操作(request header中带token参数).
      operationId: updateUserById
      parameters:
        - name: adaccount
          in: path
          description: AD 账号
          required: true
          schema:
            type: string
        - name: token
          in: header
          description: 授权码
          required: true
          schema:
            type: string
      responses:
        '400':
          description: 参数错误
        '401':
          description: 无权限（APP）
        '404':
          description: 用户不存在
  '/api/ad/deleteuser/{adaccount}':
    delete:
      tags:
        - user
      summary: 删除一个用户
      description: 需要验证授权码后才能操作.
      operationId: deleteUserById
      parameters:
        - name: adaccount
          in: path
          description: AD 账号
          required: true
          schema:
            type: string
        - name: token
          in: header
          description: 授权码
          required: true
          schema:
            type: string
      responses:
        '400':
          description: 参数错误
        '401':
          description: 无权限（APP）
        '404':
          description: 用户不存在
servers:
  - url: 'https://virtserver.swaggerhub.com/xxxx/Active-Directory-API/1.8.0'
  - url: 'http://virtserver.swaggerhub.com/xxxx/Active-Directory-API/1.8.0'
components:
  requestBodies:
    UserArray:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'
      description: List of user object
      required: true
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'http://petstore.swagger.io/oauth/dialog'
          scopes:
            'write:pets': modify pets in your account
            'read:pets': read your pets
    api_key:
      type: apiKey
      name: api_key
      in: header
  schemas:
    User:
      type: object
      properties:
        code:
          type: integer
          format: int4
          description: 状态码
        msg:
          type: string
          description: 返回提示
        fullname:
          type: string
          description: 用户全名
        groups:
          type: string
          description: 用户组列表
        email:
          type: string
          description: 邮箱
        token:
          type: string
          description: 授权码
        timestamp:
          type: string
          description: 授权时间
      xml:
        name: User