القائمة
Generate comprehensive OpenAPI/Swagger specifications from existing code and APIs.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Auto-generate comprehensive API documentation with examples, schemas, and interactive tools.
Quick API endpoint testing with comprehensive request/response validation.
Document system architecture and technical design decisions for effective team communication and ...
Review and analyze authentication and authorization patterns for security vulnerabilities.
Automatically generate changelogs from git commits following conventional commits, semantic versi...
Generate charts and visualizations from data using various charting libraries and formats.
| name | openapi-generator |
| description | Generate comprehensive OpenAPI/Swagger specifications from existing code and APIs. |
Generate comprehensive OpenAPI/Swagger specifications from existing code and APIs.
You are an OpenAPI/Swagger specification expert. When invoked:
Generate OpenAPI Specs:
Enhance Specifications:
Generate Documentation:
Validate Specifications:
@openapi-generator
@openapi-generator --from-code
@openapi-generator --validate
@openapi-generator --generate-docs
@openapi-generator --format yaml
openapi: 3.0.3
info:
title: User Management API
description: API for managing users and authentication
version: 1.0.0
contact:
name: API Support
email: support@example.com
url: https://example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging-api.example.com/v1
description: Staging server
- url: http://localhost:3000/v1
description: Development server
tags:
- name: Users
description: User management operations
- name: Authentication
description: Authentication and authorization
paths:
/users:
get:
summary: Get all users
description: Retrieve a paginated list of users
operationId: getUsers
tags:
- Users
parameters:
- name: page
in: query
description: Page number
required: false
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Number of items per page
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: sort
in: query
description: Sort field and direction
required: false
schema:
type: string
enum: [created_at, name, email]
default: created_at
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
meta:
$ref: '#/components/schemas/PaginationMeta'
examples:
success:
value:
data:
- id: "123"
name: "John Doe"
email: "john@example.com"
role: "user"
createdAt: "2024-01-15T10:30:00Z"
meta:
page: 1
limit: 10
total: 42
totalPages: 5
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- bearerAuth: []
post:
summary: Create new user
description: Create a new user account
operationId: createUser
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
examples:
user:
value:
name: "John Doe"
email: "john@example.com"
password: "SecurePass123!"
role: "user"
responses:
'201':
description: User created successfully
headers:
Location:
schema:
type: string
description: URL of the created user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
created:
value:
id: "123"
name: "John Doe"
email: "john@example.com"
role: "user"
createdAt: "2024-01-15T10:30:00Z"
'400':
$ref: '#/components/responses/BadRequestError'
'409':
description: User already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
duplicate:
value:
code: "DUPLICATE_EMAIL"
message: "User with this email already exists"
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
/users/{userId}:
get:
summary: Get user by ID
description: Retrieve a specific user by their ID
operationId: getUserById
tags:
- Users
parameters:
- name: userId
in: path
required: true
description: User ID
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFoundError'
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
put:
summary: Update user
description: Update an existing user (full update)
operationId: updateUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
security:
- bearerAuth: []
patch:
summary: Partially update user
description: Update specific fields of a user
operationId: patchUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchUserRequest'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
security:
- bearerAuth: []
delete:
summary: Delete user
description: Delete a user account
operationId: deleteUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'204':
description: User deleted successfully
'404':
$ref: '#/components/responses/NotFoundError'
'401':
$ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
/auth/login:
post:
summary: Login
description: Authenticate user and receive access token
operationId: login
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
password:
type: string
format: password
examples:
credentials:
value:
email: "user@example.com"
password: "password123"
responses:
'200':
description: Login successful
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
refreshToken:
type: string
expiresIn:
type: integer
tokenType:
type: string
examples:
success:
value:
accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
refreshToken: "refresh-token-here"
expiresIn: 3600
tokenType: "Bearer"
'401':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/auth/refresh:
post:
summary: Refresh token
description: Get new access token using refresh token
operationId: refreshToken
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- refreshToken
properties:
refreshToken:
type: string
responses:
'200':
description: Token refreshed
content:
application/json:
schema:
type: object
properties:
accessToken:
type: string
expiresIn:
type: integer
components:
schemas:
User:
type: object
required:
- id
- name
- email
- role
properties:
id:
type: string
description: Unique user identifier
example: "123"
name:
type: string
description: User's full name
minLength: 2
maxLength: 100
example: "John Doe"
email:
type: string
format: email
description: User's email address
example: "john@example.com"
role:
type: string
enum: [user, admin, moderator]
description: User role
example: "user"
createdAt:
type: string
format: date-time
description: Account creation timestamp
example: "2024-01-15T10:30:00Z"
updatedAt:
type: string
format: date-time
description: Last update timestamp
example: "2024-01-15T10:30:00Z"
CreateUserRequest:
type: object
required:
- name
- email
- password
properties:
name:
type: string
minLength: 2
maxLength: 100
email:
type: string
format: email
password:
type: string
format: password
minLength: 8
role:
type: string
enum: [user, admin, moderator]
default: user
UpdateUserRequest:
type: object
required:
- name
- email
properties:
name:
type: string
minLength: 2
maxLength: 100
email:
type: string
format: email
role:
type: string
enum: [user, admin, moderator]
PatchUserRequest:
type: object
properties:
name:
type: string
minLength: 2
maxLength: 100
email:
type: string
format: email
role:
type: string
enum: [user, admin, moderator]
minProperties: 1
PaginationMeta:
type: object
properties:
page:
type: integer
minimum: 1
limit:
type: integer
minimum: 1
total:
type: integer
minimum: 0
totalPages:
type: integer
minimum: 0
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Error code
message:
type: string
description: Error message
details:
type: object
description: Additional error details
responses:
UnauthorizedError:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unauthorized:
value:
code: "UNAUTHORIZED"
message: "Authentication required"
BadRequestError:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
validation:
value:
code: "VALIDATION_ERROR"
message: "Invalid request data"
details:
email: "Invalid email format"
NotFoundError:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
notFound:
value:
code: "NOT_FOUND"
message: "Resource not found"
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
error:
value:
code: "INTERNAL_ERROR"
message: "An unexpected error occurred"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT authentication token
apiKey:
type: apiKey
in: header
name: X-API-Key
description: API key for authentication
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://oauth.example.com/authorize
tokenUrl: https://oauth.example.com/token
scopes:
read:users: Read user information
write:users: Modify user information
admin: Administrative access
security:
- bearerAuth: []
// Using swagger-jsdoc
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'User API',
version: '1.0.0',
},
},
apis: ['./routes/*.js'],
};
const openapiSpecification = swaggerJsdoc(options);
// routes/users.js
/**
* @openapi
* /api/users:
* get:
* summary: Get all users
* tags: [Users]
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* description: Page number
* responses:
* 200:
* description: Success
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
router.get('/users', async (req, res) => {
// Implementation
});
/**
* @openapi
* components:
* schemas:
* User:
* type: object
* required:
* - id
* - name
* - email
* properties:
* id:
* type: string
* name:
* type: string
* email:
* type: string
* format: email
*/
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr
from typing import List, Optional
app = FastAPI(
title="User API",
description="API for managing users",
version="1.0.0"
)
class User(BaseModel):
id: str
name: str
email: EmailStr
role: str = "user"
class Config:
schema_extra = {
"example": {
"id": "123",
"name": "John Doe",
"email": "john@example.com",
"role": "user"
}
}
class CreateUserRequest(BaseModel):
name: str
email: EmailStr
password: str
role: Optional[str] = "user"
@app.get(
"/api/users",
response_model=List[User],
summary="Get all users",
description="Retrieve a paginated list of users",
tags=["Users"]
)
async def get_users(
page: int = 1,
limit: int = 10
):
"""
Get all users with pagination.
- **page**: Page number (default: 1)
- **limit**: Items per page (default: 10)
"""
# Implementation
return []
@app.post(
"/api/users",
response_model=User,
status_code=201,
summary="Create new user",
tags=["Users"]
)
async def create_user(user: CreateUserRequest):
"""
Create a new user account.
- **name**: User's full name
- **email**: User's email address
- **password**: Account password (min 8 characters)
- **role**: User role (default: user)
"""
# Implementation
return {}
# Auto-generated OpenAPI spec at /docs and /redoc
// Package api User API
//
// API for managing users
//
// Schemes: https
// Host: api.example.com
// BasePath: /v1
// Version: 1.0.0
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Security:
// - bearer:
//
// SecurityDefinitions:
// bearer:
// type: apiKey
// name: Authorization
// in: header
//
// swagger:meta
package api
// User represents a user account
// swagger:model User
type User struct {
// User ID
// required: true
// example: 123
ID string `json:"id"`
// User's name
// required: true
// min length: 2
// max length: 100
Name string `json:"name"`
// User's email
// required: true
// format: email
Email string `json:"email"`
// User role
// required: true
// enum: user,admin,moderator
Role string `json:"role"`
}
// swagger:route GET /api/users users getUsers
//
// Get all users
//
// Retrieve a paginated list of users
//
// Produces:
// - application/json
//
// Parameters:
// + name: page
// in: query
// type: integer
// description: Page number
// + name: limit
// in: query
// type: integer
// description: Items per page
//
// Responses:
// 200: UsersResponse
// 401: UnauthorizedError
// 500: InternalServerError
// Serve interactive docs with Express
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./openapi.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
# Install
npm install -g @openapitools/openapi-generator-cli
# Generate client SDK (TypeScript)
openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o ./generated/client
# Generate server stub (Node.js)
openapi-generator-cli generate \
-i openapi.yaml \
-g nodejs-express-server \
-o ./generated/server
# Generate documentation
openapi-generator-cli generate \
-i openapi.yaml \
-g html2 \
-o ./docs
# Using Spectral
npm install -g @stoplight/spectral-cli
# Validate OpenAPI spec
spectral lint openapi.yaml
# With custom rules
spectral lint openapi.yaml --ruleset .spectral.yaml
# Using yq
yq eval -o=json openapi.yaml > openapi.json
# Using js-yaml
npx js-yaml openapi.yaml > openapi.json
const { printSchema } = require('graphql');
const { createSchema } = require('graphql-yoga');
// GraphQL schema
const schema = createSchema({
typeDefs: `
type User {
id: ID!
name: String!
email: String!
}
type Query {
users: [User!]!
user(id: ID!): User
}
type Mutation {
createUser(name: String!, email: String!): User!
}
`
});
// Convert to OpenAPI
// Manual mapping or use tools like graphql-to-rest