Bits of .NET

📖 OpenAPI = API Documentation

Good APIs need good docs. OpenAPI provides standardized, interactive documentation for your REST APIs.

📝 OpenAPI Specification

# openapi.yaml
openapi: 3.0.0
info:
    title: My API
    version: 1.0.0
    description: API documentation

paths:
    /users:
        get:
            summary: Get all users
            description: Returns a list of users
            parameters:
                - name: page
                  in: query
                  schema:
                      type: integer
                      default: 1
                - name: limit
                  in: query
                  schema:
                      type: integer
                      default: 20
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/User'

    /users/{id}:
        get:
            summary: Get user by ID
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: integer
            responses:
                200:
                    description: User found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/User'
                404:
                    description: User not found

components:
    schemas:
        User:
            type: object
            properties:
                id:
                    type: integer
                name:
                    type: string
                email:
                    type: string
                created_at:
                    type: string
                    format: date-time

🎯 Tools and Integration

# Swagger UI
npm install swagger-ui-express

// Server Setup
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./openapi.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

# ReDoc
npm install redoc-express
const redoc = require('redoc-express');

app.get('/api-docs', redoc({
    title: 'API Documentation',
    specUrl: '/openapi.json'
}));

# Code Generation
openapi-generator generate -i openapi.yaml -g typescript-axios

# Validation
npm install swagger-cli
swagger-cli validate openapi.yaml

# Testing
npm install @openapi-contrib/openapi-schema-to-json-schema

# Security
npm install swagger-parser
swagger-parser validate openapi.yaml

💡 API Documentation Tips

• Keep documentation up-to-date
• Use examples in documentation
• Include error responses
• Add authentication details
• Provide interactive testing