Unlimited WordPress themes, graphics, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Automation
Code

Pemrograman Menggunakan Yii: Menghasilkan Dokumentasi

by
Difficulty:IntermediateLength:ShortLanguages:
This post is part of a series called How to Program With Yii2.
Programming With Yii2: Building Community With Voting, Comments, and Sharing
This post is part of a series called Building Your Startup With PHP.
How to Build a User Tour With Shepherd in JavaScript

Indonesian (Bahasa Indonesia) translation by Yanti Baddolo (you can also view the original English article)

Final product image
What You'll Be Creating

Dalam seri pemrograman menggunakan Yii2 ini, saya membimbing pembaca dalam menggunakan Framework Yii2 untuk PHP. Anda mungkin juga tertarik dengan pengenalan saya tentang Framework Yii, yang mengulas kelebihan-kelebihan Yii dan termasuk sebuah gambaran dari fitur terbaru dalam Yii 2.x.

Selamat datang! Sebelumnya, saya menulis tentang membangun REST API untuk aplikasi Yii anda dan memperluar kustom API untuk seri aplikasi startup kami, Meeting Planer.

Pada tutorial hari ini, saya akan memperkenalkan anda pada ekstensi apidoc Yii, yang secara otomatis menghasilkan dokumentasi yang dapat diakses untuk kode anda. Saya akan menggunakannya untuk menghasilkan dokumentasi API untuk Meeting Planner.

Permulaan

Programming With Yii - APIdoc installation Guide

Instalasi apidoc sangatlah mudah. Sebagaimana yang ditunjukkan diatas, anda hanya perlu menambahkan paket apidoc menggunakan Composer.

Sebagai tambahan untuk menghasilkan dokumentasi dari kode, fitur ini juga mampu menghasilkan dokumentasi dari penurunan harga dan mengubahnya menjadi bentuk PDF.

Sebagai contoh, berikut ini dokumentasi Framework Yii, berbentuk dokumentasi kode:

Programming With Yii - Auto-Generated Framework Documentation

Dan, berikuti ini panduan Yii2, yang saya yakin dihasilkan dari penurunan harga terintegrasi dengan dokumentasi kode agar mudah diakses:

Programming With Yii Generating Documentation - Guide generated from Markdown

Panduan yang Dihasilkan dari Penurunan Harga Berikut ini  syntax dokumentasi didukung apidoc; berdasarkan phpdoc.

Ironisnya, dokumentasi untuk apidoc belumlah lengkap, akan tetapi mudah digunakan untuk auto-dokumentasi dasar.

Menghasilkan Dokumentasi API

Jika anda mengikuti seri-seri startup saya, anda tentu meyadari saya membuat sebuah API ekstensif untuk mendukung aplikasi mobile saya, dan sebagainya. Apidoc merupakan jalan yang ideal bagi saya untuk menyokong auto dokumentasi dinamis untuk hal tersebut.

Tentunya terdapat banyak sekali layanan-layanan dari web lain yang dapat membantu anda mendokumentasikan API anda, akan teteapi saya melihat bahwa apidoc dari Yii bekerja dengan baik untuk kebutuhan-kebutuhan saya, dan saya mengapresiasi tema phpdoc-style yang digunakan.

Menggunakan pola mengomentari yang standar membuatnya seperti layanan-layanan lain yang menjadikannya dapat dengan mudah membuat dokumentasi dari kode MeetingPlanner jika saya menggunakan layanan-layanan lain tersebut.

Membuat Blok Komentar

Pada dasarnya, anda membuat komentar dalam kode anda yang digunakan apidoc untuk membangun komentar anda. Hal ini telah dijelaskan dalam panduan pola membuat kode dengan Yii.

Letakkan blok komentar pada bagian teratas dari tiap-tiap file seperti berikut:

Dan letakkan blok komentar diatas masing-masing definisi kontroller atau model:

Kemudian, letakkan detail blok komentar diatas masing-masing method, yang mengandung parameter, nilai return, dan exeptions:

Anda harus mengikuti layout prescribed sebagaimana yang dideskripsikan untuk menyumpalkan apidoc dengan sukses.

Menggunakan Placeholder Arguments untuk Dokumentasi API

Tim Yii telah mengembangkan Apidoc untuk menghasilkan dokumentasi kode. Bagaimanapun, sebagaimana yang saya tulis mengenai Pengamanan API Anda, seluruhnya kecuali argument hash signature telah dipindahkan pada header http. Ini tidak terlihat oleh apidoc. Oleh Karena itu, untuk menghasilkan dokumentasi API, saya memutuskan untuk menggunakan sebuah solusi.

Sebagaimana yang dapat anda lihat, saya memasukkan argumen-argumen buatan pada method-method kemudian menjelaskannya pada komentar-komentar sehingga dikirim sebagai header atau “dalam header”

Selama nilai default termasuk dalam definisi fungsi, tidak akan ada yang berbahaya:

Untuk sesaat, anda akan melihat bagaimana hal ini umumnya bekerja untuk dokumentasi API, meskipun jika bukan merupakan gaya kode yang optimal.

Mari berpindah pada cara menggunakan apidoc yang sebenarnya untuk menghasilkan dokumentasi.

Menghasilkan Dokumentasi

Anda dapat mengulas perintah-perintah dalam apidoc dengan menjalankannya tanpa argumen:

saya akan menggunakan opsi api, dan berikut ini konfigurasi yang dapat anda buat:

Untuk menghasilkan dokumentasi API saya, yang mana direktorinya juga merupakan api, saya melakukan hal berikut:

Karena saya belum selesai menuliskan komentar pada seluruh induk, maka terdapat banyak error dan peringatan yang dihasilkan. Pada umumnya mereka tampak seperti berikut:

Mengakses Dokumentasi

Mengunggah dokumentasi diatas baris perintah apidoc pada /api/web/docs bermakna bahwa anda dapat mengakses dokumentasi Meeting Planner dari situsnya.

Sebagai contoh, berikut ini UserTokenController:

Programming With Yii Generating Documentation - UserTokenController Example

Berikut ini method actionRegister() menunjukkan parameter komentar yang terefleksi dari informasi in header.

Programming With Yii Generating Documentation - UserTokenController Example actionRegister method

Berikut ini dokumentasi MeetingController:

Programming With Yii Generating Documentation - MeetingController Example

Dan berikut ini method actionMeetingplacechoices():

Programming With Yii Generating Documentation - MeetingController Example actionMeetingplaces example

Sebagaimana yang dapat anda lihat, hal ini sangat berguna untuk berbagi API dengan programmer pihak ketiga dalam waktu yang singkat saat anda mengirimkan kode. Keuntungan yang paling hebat ialah dapat mengeliminasi kebutuhan untuk secara manual memelihara dokumentasi API secara terpisah.

Kapanpun anda dapat mengeliminasi sebuah tugas untuk sebuah startup, itu merupakan kemenangan yang besar.

Melihat kedepan

Saya hara panda telah menyaksikan sebagian kecil kekuatan ekstensi apidoc Yii2. Anda dapat menggunakannya untuk mempertahankan dokumentasi untuk seluruh kode anda. Dan juga mendorong anda untuk tetap terus berkomentar, yang mana saya akan lebih melakukannya sekarang.

Jika anda memiliki pertanyaan atau umpan balik, tolong posting pada komentar. Jika anda ingin terus mengikuti tutorial-tutorial Envato Tuts+ saya kedepannya dan seri-seri yang lain, anda dapat mengunjungi halaman instruktur saya atau dengan mengikuti @reifman. Terus ikuti seri startup saya dan Meeting Planner.

Link Terkait

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.