Api-blueprint: Mengatur lebih dari satu bagian di dalam grup

@spark-ftw Sayangnya heading pertama Authentication hanya dilampirkan pada deskripsi untuk grup sumber daya Print . Deskripsi ditampilkan langsung di bawah judul sumber daya dan kemudian semua sumber daya tercantum di bawah ini.

Saya sarankan refactoring ini sedikit untuk mengelompokkan grup sumber daya yang berbeda sebagai berikut:

• Grup Otentikasi
  
  
  
  • Koleksi sumber daya pengguna
  
  
  • Daftar semua pengguna
  
  
  • Daftarkan akun pengguna baru
  
  
• Grup Cetak
  
  
  
  • ...
  
  

Seperti yang Anda lihat pada gambar terlampir, saya sudah memiliki grup - itu adalah "Grup cetak" dan "Otentikasi" dan "Cetak dokumen" adalah anak-anak dari "Grup cetak" sehingga solusi Anda tidak berfungsi untuk saya. Apakah Anda punya ide lain?

Terima kasih

@spark-ftw Apa yang dimaksud @kylef benar. Anda tidak dapat memiliki deskripsi penurunan harga acak di dalam grup sumber daya ( Group Print ) setelah Anda menjelaskan sumber daya ( User Collection ).

Anda dapat melakukan sesuatu seperti ini. (itulah yang diusulkan @kylef ).

# Group Authentication

## Authentication
Resource related to user auth

## User collection [/users]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

# Group Print

## Print docs
Resource related to prints

## Print collection [/print]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

EDIT : Memperbarui komentar setelah memperbaiki kesalahan kecil.

Ini tidak membantu saya, karena saya memerlukan beberapa bagian di dalam setiap bagian seperti:

• Bagian Cetak

-- Grup autentik

--- Koleksi pengguna

--- Koleksi autentik

-- Grup Dokumen

--- Cetak koleksi dokumen

--- Simpan koleksi dokumen

• Bagian Drive

-- Grup autentik

--- Koleksi pengguna

--- Koleksi autentik

-- Grup Dokumen

--- Cetak koleksi dokumen

--- Simpan koleksi dokumen

...

Terima kasih

Ada ide?

@spark-ftw Saya telah menambahkan beberapa !comments ke dalam kode di bawah ini. TL;DR Judul Anda ##Autentikasi adalah bagian dari deskripsi Grup, bukan bagian dari deskripsi Sumber Daya. Setelah Anda menentukan titik akhir pertama dalam sebuah grup, Anda baru saja mengakhiri Deskripsi-Grup dan mulai dengan Titik Akhir Sumber Daya.

FORMAT: 1A
HOST: https://sample

# sampleapi
Sample API

! group definition starts here with name, and description following
# Group Print
Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum 

## Authentication <--- part of description above
Resource related to user auth <--- part of description above

! First endpoint definition starts here, group description ends here.
## User collection [/users]
### List all users [GET]
+ Response 200 (application/json)
        [...]

### Register new user account [POST]
+ Request (application/json)
            { ... }
+ Response 201
    + Headers
            Location: https://sample

## Print docs <-- this is not another endpoint / resource definition, but a description instead...
Resource related to prints <-- this is not another endpoint / resource definition, but a description instead...

! another resource endpoint is defined below, that is ok.
## Print collection [/print]
### List all users [GET]
+ Response 200 (application/json)
    [...]

OK, jadi bagaimana saya bisa mencapai struktur yang saya inginkan?

@spark-ftw Anda tidak dapat memiliki judul yang Anda inginkan jika Anda bersikeras pada struktur pohon. Anda masih dapat menggunakan beberapa grup sebagai:

Group Print Authentication
  - User Collection
    - List all
    - Register new...
Group Print Docs
Group Drive Authentication
Group Drive Docs
...

Maaf, tapi saya tidak melihat solusi lain untuk menggunakan lebih banyak Grup. Tetapi Anda akan mendapat manfaat dengan itu - karena navigasi dalam dokumentasi di Apiary menggunakan Grup ini. Jadi ini adalah win-win solution.

Silakan lihat permintaan saya lagi:

-Bagian Cetak

-- Grup autentik

--- Koleksi pengguna

--- Koleksi autentik

-- Grup Dokumen

--- Cetak koleksi dokumen

--- Simpan koleksi dokumen

Bagian Drive

-- Grup autentik

--- Koleksi pengguna

--- Koleksi autentik

-- Grup Dokumen

--- Cetak koleksi dokumen

--- Simpan koleksi dokumen

Selain Print, saya juga membutuhkan produk Drive. Ini adalah sesuatu yang lain (jadi saya perlu tingkat hierarki lain)

Omong-omong, penurunan harga mendukung ini, hanya tempat pemeliharaan lebah yang memiliki masalah dengan menguraikannya ...

@spark-ftw Bukannya Perapian memiliki masalah - itu karena deskripsi antara Titik Akhir Sumber Daya tidak diizinkan berada di sana - jika Anda melihat Peringatan/Masalah di Editor Apiary, Anda akan melihat Peringatan di sana. Menurut spesifikasi https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - bagian Group berisi bagian-bagian ini: Nama Grup , Deskripsi Grup, Sumber Daya Grup. Tidak ada deskripsi lain di antaranya.

Jika membandingkan Markdown vs. API Blueprint - Anda akan diakhiri dengan struktur linier non-pohon sebagai gantinya.

@spark-ftw Harap dicatat bahwa kata kunci Group digunakan untuk menunjukkan awal baru Section .
API Blueprint sama sekali tidak mendukung penyarangan tingkat ketiga - silakan lihat file spesifikasi yang ditautkan dalam komentar di atas.

Jadi tidak ada solusi untuk masalah saya?