Example of documentation using swagger write in yaml

example-swagger-user.yaml

swagger: "2.0"
info:
  description: "Prover acesso ao recurso de usuários."
  version: "0.0.1"
  title: "Lista de Usuários"
  termsOfService: "http://swagger.io/terms/"
  contact:
    name: Paulo
    email: "[email protected]"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "api.meusite.com"
basePath: "/v1"
tags:
- name: "users"
  description: "Endpoint relacionado ao recurso de usuário"
  externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
schemes:
- "https"
- "http"
paths:
  /users:
    get:
      tags:
      - "users"
      summary: "Lista de usuários"
      description: "Recurso responsável por retornar **todos** os usuários"
      operationId: "getUsers"
      responses:
        "200":
          description: "retorna um array de usuários"
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        "500":
          description: "Erro interno do servidor"
          schema: 
            $ref: '#/definitions/Error'
        "default": 
          description: "Erro inesperado"
          schema: 
            $ref: '#/definitions/Error'
    post:
      tags:
        - "users"
      summary: "Cadastra um usuário"
      description: "Recurso responsável por cadastrar um usuário"
      operationId: "createUser"
      parameters:
        - name: user
          in: body
          description: usuário
          required: true
          schema: 
            $ref: '#/definitions/User'
      responses:
          "201":
            description: "Usuário cadastrado com sucesso"
            schema:
              $ref: '#/definitions/User'
          "500":
            description: "Erro interno do servidor"
            schema: 
              $ref: '#/definitions/Error'
          "default": 
            description: "Erro inesperado"
            schema: 
              $ref: '#/definitions/Error'
  /users/{id}:
    get:
      tags:
      - "users"
      summary: "Lista um usuário especifico"
      description: "Recurso responsável por retornar um usuário **especifico**"
      operationId: "getUserId"
      parameters:
        - name: id
          in: path
          description: ID of order that needs to be fetched
          required: true
          type: integer
      responses:
        "200":
          description: "retorna um usuario"
          schema:
            $ref: '#/definitions/User' 
        "500":
          description: "Erro interno do servidor"
          schema: 
            $ref: '#/definitions/Error'
        "default": 
          description: "Erro inesperado"
          schema: 
            $ref: '#/definitions/Error'
    put:
      tags:
        - "users"
      summary: "Cadastra um usuário"
      description: "Recurso responsável por cadastrar um usuário"
      operationId: "updateUser"
      parameters:
        - name: id
          in: path
          description: ID of order that needs to be fetched
          required: true
          type: integer
        - name: user
          in: body
          description: usuário
          required: true
          schema: 
            $ref: '#/definitions/User'
      responses:
          "200":
            description: "Usuário atualizado com sucesso"
            schema:
              $ref: '#/definitions/User'
          "404":
            description: "Usuário não encontrado"
            schema: 
              $ref: '#/definitions/Error'
          "500":
            description: "Erro interno do servidor"
            schema: 
              $ref: '#/definitions/Error'
          "default": 
            description: "Erro inesperado"
            schema: 
              $ref: '#/definitions/Error'
    patch:
      tags:
        - "users"
      summary: "Cadastra um usuário"
      description: "Recurso responsável por cadastrar um usuário"
      operationId: "updatePartialUser"
      parameters:
        - name: id
          in: path
          description: ID of order that needs to be fetched
          required: true
          type: integer
        - name: user
          in: body
          description: usuário
          required: true
          schema: 
            $ref: '#/definitions/User'
      responses:
          "200":
            description: "Usuário atualizado com sucesso"
            schema:
              $ref: '#/definitions/User'
          "404":
            description: "Usuário não encontrado"
            schema: 
              $ref: '#/definitions/Error'
          "500":
            description: "Erro interno do servidor"
            schema: 
              $ref: '#/definitions/Error'
          "default": 
            description: "Erro inesperado"
            schema: 
              $ref: '#/definitions/Error'
    delete:
      tags:
      - "users"
      summary: "Lista um usuário especifico"
      description: "Recurso responsável por retornar um usuário **especifico**"
      operationId: "deleteUserId"
      parameters:
        - name: id
          in: path
          description: ID of order that needs to be fetched
          required: true
          type: integer
      responses:
        "204":
          description: "Usuário deletado com sucesso"
        "404":
          description: "Usuário não encontrado"
          schema: 
            $ref: '#/definitions/Error'
        "410":
          description: "Usuário não disponivel"
        "500":
          description: "Erro interno do servidor"
          schema: 
            $ref: '#/definitions/Error'
        "default": 
          description: "Erro inesperado"
          schema: 
            $ref: '#/definitions/Error'
definitions:
  User:
    type: "object"
    required:
      - name
      - email
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "Identificador unico do usuário"
      name:
        type: "string"
        description: "Nome do usuário"
      email:
        type: "string"
        description: "Email do usuário"
    xml:
      name: "User"
  Error: 
    type: object
    properties:
      code:
        type: integer
        format: int32
        description: "codigo do status do erro"
      message:
        type: string
        description: "mensagem do erro"
      fields:
        type: string
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"