Api-blueprint: Memperluas Struktur Data

Dibuat pada 12 Nov 2015 · 6Komentar · Sumber: apiaryio/api-blueprint

Hai, Saya punya pertanyaan/proposal tentang struktur data. Mungkin ini lebih terkait MSON tetapi saya akan mulai di sini. Untuk menjaga struktur data tetap bagus dan rapi, saya ingin data duplikat sesedikit mungkin, oleh karena itu alangkah baiknya jika struktur data dapat saling memperluas.

Asumsikan struktur data berikut:

# Data Structures

## Project_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project1_Get (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)

Dalam atribut links dari Project1_Get Saya menggunakan kembali objek Project_Link yang berfungsi dengan baik. Tapi misalkan saya membutuhkan DataStructure berikut juga:

## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

Sekarang ada data duplikat dalam struktur data saya karena Project1_Identifier berisi atribut type dan id , tetapi juga berisi Project1_Get . Akan sangat bagus jika saya bisa melakukan hal berikut:

# Data Structures

## Project1_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1_Get (Project_Identifier) <--- Extend!
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project1_Link, required)

Dalam contoh berikut, drafter mengembalikan kesalahan:

FORMAT: 1A
HOST: https://test.api.com/

# Test API
Hi, welcome to the API!

# Group Projects
Wow, we are using projects!

### Retrieve single project [GET /projects/{id}]
+ Parameters
    + id: `5` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (Project1_Get, required)

# Data Structures

## Project_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1_Get (Project_Identifier)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)

user<strong i="25">@development</strong>:/srv/www/docs$ drafter -v
v2.0.0-pre.1
user<strong i="26">@development</strong>:/srv/www/docs$ drafter --validate docs.md --use-line-num

error: (4)  base type 'Project1_Get' is not defined in the document; line 16, column 11 - line 16, column 40
warning: (8)  unable to find the symbol `Project1_Get` in the list of named types; line 16, column 11 - line 16, column 40

Language Parser Implementation Bug

Sumber

robbinjanssen

Komentar yang paling membantu

@robbinjanssen Jika Anda ingin mereka berada di atas, lakukan sesuatu seperti ini:

## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

pksunkara pada 12 Nov 2015

👍4 ❤2

Semua 6 komentar

Ini harus mungkin. Sepertinya masalahnya ada pada _ dalam nama tipe. Mengganti nama Project1_Get menjadi X sepertinya berhasil.

Catatan _ adalah karakter yang dicadangkan per spesifikasi MSON – lihat https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#6 -reserved-characters--keywords

Namun saya yakin kami memiliki bug di sini dalam implementasi kami cc @pksunkara

zdne pada 12 Nov 2015

Anda benar, drafter sekarang menyetujui penurunan harga menggunakan contoh berikut:

FORMAT: 1A
HOST: https://test.api.com/

# Test API
Hi, welcome to the API!

# Group Projects
Wow, we are using projects!

### Retrieve single project [GET /projects/{id}]
+ Parameters
    + id: `5` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (Project1Get, required)

# Data Structures

## ProjectLink (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## ProjectIdentifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1Get (ProjectIdentifier)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

~~Tapi memang saya pikir itu bug, baik antarmuka aglio dan apiaryio membuatnya salah:~~

screen shot 2015-11-12 at 11 14 41

Sunting: ups, saya melihat apiaryio merendernya dengan benar! Tapi itu menempatkan tipe/id di bagian bawah dalam kasus ini. Preferensi saya akan menempatkannya di atas.

Saya akan menunggu sebelum memfaktorkan ulang dokumen saya lagi ;-)

robbinjanssen pada 12 Nov 2015

@robbinjanssen Jika Anda ingin mereka berada di atas, lakukan sesuatu seperti ini:

## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

pksunkara pada 12 Nov 2015

👍4 ❤2

@pksunkara keren terima kasih!

robbinjanssen pada 12 Nov 2015

Contoh sederhana dari bug adalah sebagai berikut:

# GET /projects

+ Response 200 (application/json)
    + Attributes (object)
        + data (B_B, required)

# Data Structures

## A_A
+ a: a

## B_B (A_A)
+ b: b

pksunkara pada 12 Nov 2015

@zdne Saya pikir ini terkait dengan https://github.com/apiaryio/snowcrash/issues/335. Apa yang kamu katakan?

pksunkara pada 12 Nov 2015

Apakah halaman ini membantu?

0 / 5 - 0 peringkat