api

API

This is a template API implementation using Go and the Gin framework, with automatic Swagger documentation generation.

Technology Stack

• Go - Programming language
• Gin - Web framework
• gin-swagger - Swagger/OpenAPI documentation generation

Features

• RESTful API endpoints
• Automatic Swagger/OpenAPI documentation
• Automated Swagger 2.0 to OpenAPI 3.0.0 conversion (pure Go implementation)
• CORS support
• Health check endpoint
• Example integration with external API (JSONPlaceholder)
• Proper error handling and response formatting

Getting Started

Prerequisites

• Go 1.21 or higher
• Internet connection (for external API calls)

Installation

1. Navigate to the API directory:

   cd api

2. Install dependencies:

   go mod tidy

3. Install swag tool (for Swagger generation):

   go install github.com/swaggo/swag/cmd/swag@latest

4. Ensure swag is in your PATH (add this to your shell profile if needed):

   export PATH=$PATH:$(go env GOPATH)/bin

Running the API

1. Generate OpenAPI 3.0.0 documentation:

   # From repository root directory
   ./generate-openapi.sh

2. Start the server:

   # Manually from the api directory
   go run .
   
   # Makefile from root directory
   make run_api_dev

The API will be available at http://localhost:8080

API Endpoints

• GET /api/v1/health - Health check
• GET /api/v1/posts - (Sample) Get all posts from JSONPlaceholder
• GET /api/v1/posts/{id} - (Sample) Get a specific post by ID
• GET /swagger/index.html - Swagger UI documentation
• POST /api/v1/directions/bicycle - 自転車ルート検索
• GET /api/v1/search?q={検索キーワード} - 目的地候補取得
  • ここから取得 https://wiki.openstreetmap.org/wiki/JA:Nominatim

Swagger Documentation

The API automatically generates OpenAPI/Swagger documentation through the following workflow:

1. Swagger 2.0 Generation: swag init generates Swagger 2.0 format in docs/swagger.json
2. Conversion to OpenAPI 3.0.0: A Go converter transforms it to OpenAPI 3.0.0 format
3. Output: Final specification is placed in ../openapi-specifications/api.swagger.json

The documentation is:

• Served at /swagger/index.html when the server is running (Swagger 2.0 format)
• Available as OpenAPI 3.0.0 in ../openapi-specifications/api.swagger.json for tooling

Development

To regenerate OpenAPI 3.0.0 documentation after making changes:

Complete workflow (Recommended):

# From repository root
./generate-openapi.sh

This script will:

1. Run swag init to generate Swagger 2.0 documentation in api/docs/
2. Test that npm run gen-schema and npm run mock work correctly

Manual steps:

# 1. Generate Swagger 2.0
cd api && swag init && cd ..

# 2. Test React Native tooling
cd mobile-app
npm run gen-schema  # Generate TypeScript definitions
npm run mock        # Start mock server on port 3001