API Documentation Standards

FORMAT: 1A

# My API

API description here.

# Group Users

## User [/users/{id}]

+ Parameters
    + id: 123 (number, required) - User ID

### Get User [GET]

+ Response 200 (application/json)

        {
            "id": 123,
            "name": "Nguyễn Văn A",
            "email": "vana@example.com"
        }

+ Response 404 (application/json)

        {
            "error": "User not found"
        }

## Users Collection [/users]

### Create User [POST]

+ Request (application/json)

        {
            "name": "Nguyễn Văn B",
            "email": "vanb@example.com"
        }

+ Response 201 (application/json)

        {
            "id": 456,
            "name": "Nguyễn Văn B",
            "email": "vanb@example.com"
        }

#%RAML 1.0
title: My API
version: v1
baseUri: https://api.example.com/{version}
mediaType: application/json

types:
  User:
    type: object
    properties:
      id: integer
      name: string
      email:
        type: string
        pattern: ^.+@.+\..+$

traits:
  pageable:
    queryParameters:
      page:
        type: integer
        default: 1
      limit:
        type: integer
        default: 20

/users:
  get:
    is: [pageable]
    responses:
      200:
        body:
          type: User[]
          example:
            - id: 123
              name: "Nguyễn Văn A"
              email: "vana@example.com"

  post:
    body:
      type: User
      example:
        name: "Nguyễn Văn B"
        email: "vanb@example.com"
    responses:
      201:
        body:
          type: User

  /{id}:
    uriParameters:
      id:
        type: integer
    get:
      responses:
        200:
          body:
            type: User
        404:
          body:
            example:
              error: "User not found"

{
  "info": {
    "name": "My API",
    "description": "API collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Users",
      "item": [
        {
          "name": "Get User",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/users/:id",
              "host": ["{{baseUrl}}"],
              "path": ["users", ":id"],
              "variable": [
                {
                  "key": "id",
                  "value": "123"
                }
              ]
            }
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"id\": 123,\n  \"name\": \"Nguyễn Văn A\"\n}"
            }
          ]
        },
        {
          "name": "Create User",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Nguyễn Văn B\",\n  \"email\": \"vanb@example.com\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/users",
              "host": ["{{baseUrl}}"],
              "path": ["users"]
            }
          }
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.example.com"
    }
  ]
}

Run collection từ command line:

# Install Newman
npm install -g newman

# Run collection
newman run my-collection.json \
  --environment production.json \
  --reporters cli,json,html

# CI/CD usage
newman run my-collection.json \
  --bail \
  --reporters junit \
  --reporter-junit-export results.xml

"""
User type represents a user in the system
"""
type User {
  """
  Unique user identifier
  """
  id: ID!

  """
  User's full name
  """
  name: String!

  """
  User's email address
  """
  email: String!

  """
  User's posts
  """
  posts: [Post!]!

  """
  When the user was created
  """
  createdAt: DateTime!
}

"""
Post type represents a blog post
"""
type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
}

"""
Root Query type
"""
type Query {
  """
  Get user by ID
  """
  user(id: ID!): User

  """
  Get all users with pagination
  """
  users(
    """
    Number of results to skip
    """
    offset: Int = 0

    """
    Maximum number of results to return
    """
    limit: Int = 20
  ): [User!]!

  """
  Search posts by title
  """
  searchPosts(query: String!): [Post!]!
}

"""
Root Mutation type
"""
type Mutation {
  """
  Create a new user
  """
  createUser(input: CreateUserInput!): User!

  """
  Update existing user
  """
  updateUser(id: ID!, input: UpdateUserInput!): User!

  """
  Delete user by ID
  """
  deleteUser(id: ID!): Boolean!
}

"""
Input type for creating user
"""
input CreateUserInput {
  name: String!
  email: String!
}

"""
Input type for updating user
"""
input UpdateUserInput {
  name: String
  email: String
}

Query - Get user với nested posts:

query GetUserWithPosts($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
    posts {
      id
      title
      publishedAt
    }
  }
}

# Variables
{
  "userId": "123"
}

Mutation - Create user:

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
    createdAt
  }
}

# Variables
{
  "input": {
    "name": "Nguyễn Văn A",
    "email": "vana@example.com"
  }
}

# cURL
curl -X GET https://api.example.com/users/123 \
  -H "Authorization: Bearer TOKEN"

// JavaScript
fetch('https://api.example.com/users/123', {
  headers: {
    'Authorization': 'Bearer TOKEN'
  }
})
.then(res => res.json())
.then(data => console.log(data));

// PHP
$ch = curl_init('https://api.example.com/users/123');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer TOKEN'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$user = json_decode($response, true);

# Python
import requests

response = requests.get(
    'https://api.example.com/users/123',
    headers={'Authorization': 'Bearer TOKEN'}
)
user = response.json()