ServiceFile

A standardized approach to describing microservices and their relationships through structured specification file and automated parsing tools.

Installation

# Install directly with Go
go install github.com/holydocs/servicefile/cmd/servicefile@latest

Quick Start

1. Document Your Service

Add structured comments to your Go code to describe your service:

/*service:name UserServicedescription: Handles user authentication and profile managementowner: team-authtags: auth, user-management, microservice*/package main
// Service that uses PostgreSQL for data storage/*service:uses PostgreSQLdescription: Stores user data and authentication tokenstechnology:postgresqlproto:tcp*/typeUserRepositorystruct {
db*sql.DB
}
// Service that provides gRPC APIs/*service:repliesdescription: Provides user management APIs to other servicestechnology:grpc-serverproto:grpc*/typeUserServerstruct {
repo*UserRepository
}
// Service that makes HTTP requests to external service/*service:requests NotificationServicedescription: Sends user notifications via email and SMStechnology:notification-serviceproto:http*/typeNotificationClientstruct {
httpClient*http.Client
}
// Service that replies to user requests/*service:replies Userdescription: Provides web interface for user interactionstechnology:http-serverproto:httpperson:true*/typeWebServerstruct {
router*gin.Engine
}

2. Generate Your ServiceFile

Use the CLI tool to generate a service file from your Go code:

# Generate from current directory
servicefile generate
# Generate from specific directory
servicefile generate --dir ./my-service
# Generate recursively (default)
servicefile generate --recursive
# Specify output file
servicefile generate --output my-service.yaml
# Disable go.mod dependency inference
servicefile generate --analyze-go-mod=false

3. Generated Output

The tool generates a servicefile.yaml with your service description:

servicefile: "0.1.0"info:
name: UserServicedescription: Handles user authentication and profile managementowner: team-authtags:
- auth
- user-management
- microservicerelationships:
- action: usesparticipant: PostgreSQLdescription: Stores user data and authentication tokenstechnology: postgresqlproto: tcp
- action: repliesdescription: Provides user management APIs to other servicestechnology: grpc-serverproto: grpc
- action: requestsparticipant: NotificationServicedescription: Sends user notifications via email and SMStechnology: notification-serviceproto: http
- action: repliesparticipant: Userdescription: Provides web interface for user interactionstechnology: http-serverproto: httpperson: true

ServiceFile Specification

Service Metadata

• servicefile: The version of the ServiceFile specification
• info.name: The name of your service
• info.description: A description of what your service does
• info.system: (Optional) The larger system or platform this service belongs to
• info.owner: (Optional) The team or individual responsible for this service
• info.repository: (Optional) The URL of repository
• info.tags: (Optional) A list of tags to categorize and organize your service

Relationship Actions

ServiceFile supports several relationship types:

• service:uses: Service depends on another service/database
• service:requests: Service makes requests to another service
• service:replies: Service provides APIs for other services/persons
• service:sends: Service sends messages/events
• service:receives: Service receives messages/events

Relationship Properties

Each relationship can have:

• participant: The name of the related service/resource
• description: Description of the relationship
• technology: Technology or product used (e.g., postgresql, redis, firebase, kafka)
• external: (Optional) Whether this is an external dependency (e.g., true, false)
• person: (Optional) Whether this relationship is with a person rather than a service or system (e.g., true, false)
• proto: (Optional) Communication protocol used (e.g., http, grpc, tcp, udp, amqp)
• tags: (Optional) A list of tags to categorize and organize the relationship (e.g., persistence, security, critical)

Multiple Services in a Single Codebase

ServiceFile supports documenting and extracting multiple services from a single codebase or monorepo. Each service should be defined with its own service:name comment block. Relationships can be attached to a specific service using the service:{service_name}:{action} format:

/*service:name UserServicedescription: Handles user authenticationtags: auth, user-management*/// service:UserService:uses DatabaseService// technology:postgres// description: Uses PostgreSQL for user data// tags:persistence, critical/*service:name NotificationServicedescription: Handles user notificationstags: notification, messaging*/// service:NotificationService:requests EmailService// technology:http// description: Requests email delivery// tags:external, email/*service:name WebServicedescription: Handles web interface and user interactionstags: web, frontend*/// service:WebService:replies User// technology:http// description: Provides web interface to users// person:true

When you run the parser, it will generate a separate YAML file for each service (e.g., userservice.servicefile.yaml, notificationservice.servicefile.yaml).

If only one service is found, the output will be a single file (e.g., servicefile.yaml).

Examples

See the internal/parser/golang/testdata/default directory for complete examples of how to document services using ServiceFile comments.