Swagger description for Secret Server

swagger.yaml

swagger: "2.0"
info:
  description: "This is an API of a secret service. You can save your secret by using the API. You can restrict the access of a secret after the certen number of views or after a certen period of time."
  version: "1.0.0"
  title: "Secret Server"
host: "api.your-secret-server.com"
basePath: "/v1"
tags:
- name: "secret"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
schemes:
- "http"
paths:
  /secret:
    post:
      tags:
      - "secret"
      summary: "Add a new secret"
      description: ""
      operationId: "addSecret"
      consumes:
      - "application/x-www-form-urlencoded"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - in: "formData"
        name: "secret"
        description: "This text will be saved as a secret"
        required: true
        type: "string"
      - in: "formData"
        name: "expireAfterViews"
        description: "The secret won't be available after the given number of views. It must be greater than 0."
        required: true
        type: "integer"
        format: "int32"
      - in: "formData"
        name: "expireAfter"
        description: "The secret won't be available after the given time. The value is provided in minutes. 0 means never expires"
        required: true
        type: "integer"
        format: "int32"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Secret"
        405:
          description: "Invalid input"
          
  /secret/{hash}:
    get:
      tags:
      - "secret"
      summary: "Find a secret by hash"
      description: "Returns a single secret"
      operationId: "getSecretByHash"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - name: "hash"
        in: "path"
        description: "Unique hash to identify the secret"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Secret"
        404:
          description: "Secret not found"
definitions:
  Secret:
    type: "object"
    properties:
      hash:
        type: "string"
        description: "Unique hash to identify the secrets"
      secretText:
        type: "string"
        description: "The secret itself"
      createdAt:
        type: "string"
        format: "date-time"
        description: "The date and time of the creation"
      expiresAt:
        type: "string"
        format: "date-time"
        description: "The secret cannot be reached after this time"
      remainingViews:
        type: "integer"
        format: "int32"
        description: "How many times the secret can be viewed"
    xml:
      name: "Secret"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"