Here we go:

openapi: 3.0.1
info:
  title: Docker-mailserver Administration API
  version: 0.0.1
servers:
  - url: 'https://contoso.com/'
paths:
  /api/admin/v1/users/{emailAddress}/changePassword:
    post:
      summary: Changes a given user's password
      tags:
        - V1 User operations
        - V1 Admin API
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: emailAddress
          required: true
          schema:
            type: string
      requestBody:
        description: The new password for the target user
        content:
          application/json:
            schema:
              type: string
      responses:
        '204':
          description: The password was successfully modified
        '404':
          $ref: '#/components/responses/UserNotFoundError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    ErrorBase:
      type: object
      required:
        - errorCode
        - message
      properties:
        errorCode:
          type: string
          description: Code name of the error
        message:
          type: string
          description: Additional details about the error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  responses:
    UserNotFoundError:
      description: User does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    UnauthorizedError:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'

You can copy & paste this in https://editor.swagger.io/ to see how it would look like

Key points:

URI prefix leaves room for both a user and an admin API (user api = self service)
URI prefix allows for separate versioning between user and admin APIs
Errors have a code and a message. The code is part of the contract, while message can change at any time. This allows callers to provide their own messages by checking the reliable errorCode
As discussed in the issues, it seems that an API key was the preferred method. This is reflected in the specification, and should be in a X-API-KEY header
Application/Json will be the only supported medium

Feel free to discuss any point from the spec in that issue.
Next step will be generating the app skeleton, I'll do it during the week. I already started, based on another spec, so there shouldn't be much to be done

Draft OpenApi Specification #1

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions