Otomatiskan pembuatan OpenAPI (Swagger) spec untuk endpoint publik OpenSID#1680
Open
pandigresik wants to merge 11 commits into
Open
Otomatiskan pembuatan OpenAPI (Swagger) spec untuk endpoint publik OpenSID#1680pandigresik wants to merge 11 commits into
pandigresik wants to merge 11 commits into
Conversation
- Update config/scribe.php with proper auth, routes, and OpenAPI config - Add artisan command scribe:copy-openapi to copy spec to repo root - Add composer scripts: generate-openapi, validate-openapi - Add openapi.yaml (initial generated spec with 54 endpoints) - Add CI workflow: openapi.yml (generate & validate on PR/push) - Update test.yml to also copy & validate OpenAPI spec - Add docs/integration-testing.md with local dev instructions - Add SCRIBE_AUTH_KEY to .env.example
- Fix CekDesa rule: lazy-load DB query in message() instead of constructor - Add missing test() method to PendudukController - Regenerate openapi.yaml (now 61 paths, covering all api.php routes) - Remove outdated note about missing endpoints from docs
- Add @group and @bodyParam/response annotations to all api/v1 controllers - Add meaningful summaries to frontend API controllers - Fix AuthController login with proper Scribe annotations - Regenerate openapi.yaml with all 61 paths properly described - Each OpenSID submission endpoint now has documented body params & response
- Remove api/frontend/* from scribe route prefixes - Regenerate spec: 21 paths, focused on OpenSID endpoints only
- Add detailed ZIP column contracts to controller docblocks - Separate JSON vs ZIP endpoints with proper @bodyParam types - Add ZIP contract validation table to docs/integration-testing.md - Add sample ZIP generator script and Pest contract test example - Each file upload endpoint now documents expected internal file format
Contributor
|
🔄 AI PR Review sedang antri di server...
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request: Otomatiskan pembuatan OpenAPI (Swagger) spec untuk endpoint publik OpenSID
Description
Menambahkan konfigurasi Scribe dan CI pipeline untuk menghasilkan OpenAPI 3.0.3 spec secara otomatis dari kode. Spec ini menjadi source of truth untuk contract tests dan onboarding integrasi OpenSID-OpenDK. Menyertakan dokumentasi runbook integrasi testing lengkap.
Changes made:
config/scribe.php— auth enabled, output OpenAPI 3.0.3, custom logo, extra_info dalam Bahasa Indonesiascribe:copy-openapi: Menyalin spec daristorage/app/scribe/openapi.yamlkeopenapi/openapi.yaml(repo root)generate-openapi(generate + copy) danvalidate-openapi(validasi YAML & struktur)openapi.yml: Jobvalidate(cek keberadaan + validasi spec) dangenerate(spin up MySQL, migrate, generate, copy, validate, cek diff, upload artifact)test.yml: Tambahan langkah generate + validate spec setelah test suite berjalan@group,@queryParam,@bodyParam,@responseuntuk Scribevendor/bin/validate-openapi.php: CLI parser YAML yang memvalidasi struktur spec & menampilkan ringkasan pathopenapi/openapi.yaml: Spec 3.0.3 mencakup 54 path — autentikasi (JWT), penduduk, pembangunan, APBDes, laporan penduduk, pesan, surat, program bantuan, identitas desa, frontenddocs/integration-testing.md: Runbook langkah-langkah: build lokal, generate spec, validasi, jalankan test (unit/feature/E2E), docker-compose, contract ZIP validation, API key management, CI pipeline referensiReason for change:
Impact of change:
✅ Validasi kontrak API otomatis: Setiap PR memvalidasi bahwa spec konsisten dengan kode
✅ Onboarding lebih cepat: Mitra/developer cukup lihat
openapi/openapi.yamlatau/api-docs✅ Source of truth terpusat: Spec versi 1.0.0 yang di-commit ke repo
✅ Dokumentasi lengkap: Runbook testing mencakup semua skenario (build, test, E2E, rotate key)
Related Issue
#1674
Steps to Reproduce
Before (problem):
After (solution):
composer generate-openapi→ menghasilkanopenapi/openapi.yaml/api-docsdi browser → dokumentasi interaktif dengan Try It OutTesting on related features:
composer generate-openapimenghasilkan YAML validcomposer validate-openapilulus (54 paths)openapi.ymlberhasil generate + validasidocs/integration-testing.mdlengkapChecklist
Technical Details
Technical Explanation
Scribe Config (
config/scribe.php):Bearer tokenvia API key), default semua endpoint terautentikasi3.0.3dengan overrideinfo.version=1.0.0GET *dengan transaksi database (tidak persist perubahan)Command
CopyOpenApiSpec:storage/app/scribe/openapi.yaml(output Scribe untuk tipelaravel)openapi/openapi.yamldengan opsi--targetkustomCI Workflow
openapi.yml:validate(ringan, tanpa DB) dangenerate(dengan MySQL service)generate: import database_test.sql, migrate, scribe:generate, copy, validate, cek git diffController Annotations:
app/Http/Controllers/Api/danApi/Auth/danApi/Frontend/ditambahi PHPDoc@groupuntuk grouping (Autentikasi, OpenSID Integration)@bodyParam,@queryParam,@responseuntuk dokumentasi parameter dan responseConfiguration changes
config/scribe.php— konfigurasi Scribe lengkap.env.example— ditambahkanSCRIBE_AUTH_KEYcomposer.json— ditambahkan scriptsgenerate-openapidanvalidate-openapiDependencies added
composer.jsonsebelumnya (tidak ditambahkan library baru)vendor/bin/validate-openapi.php— script validasi internal (bukan package)Testing
Manual Testing
composer generate-openapi— spec tergenerate tanpa errorcomposer validate-openapi— menampilkan 54 paths, valid YAML/api-docs— halaman dokumentasi interaktif tampilopenapi/openapi.yaml— struktur OpenAPI 3.0.3 validAutomated Testing
openapi.yml— job validate (tanpa DB) dan generate (dengan DB)test.yml— langkah generate + validate setelah test suiteBrowser Compatibility (if applicable)
Screenshots / Video
Before:
Tidak ada OpenAPI spec yang ter-versioning; dokumentasi API hanya dari kode.
After:
openapi/openapi.yaml(945 baris, 54 endpoints) sebagai source of truth.Breaking Changes
None — ini adalah penambahan fitur dokumentasi, tidak ada perubahan behavior endpoint.
Migration Guide
Not required.
References
Additional notes: PR ini adalah langkah pertama sebelum Issue #1673 (contract tests) dan #1676 (CI pipeline). Spec yang dihasilkan akan menjadi dasar untuk contract testing dengan OpenAPI.