search

apiaryio / api-blueprint

API Blueprint
https://apiblueprint.org
MIT License
8.65k stars 2.14k forks source link

Support multiple URI within the same resource #247

Closed juniorleota closed 9 years ago

juniorleota commented 9 years ago

We are currently trying to find a way in which we can implement 

# Folders
## Retrive FolderList [GET /folders]
## Create New Folder [POST /folders]
## Move Folder [PUT /folders/{folderPath}]
## Delete Folder [DELETE /folder/{folderPath}]

Currently this seems to put retrieve and create under the same heading, and also move and delete under the same heading due to the same URI.

We have managed to work around this in the past by having

### Folders [/folders]
#### Retrive FolderList [GET /folders]
#### Create New Folder [POST /folders]
#### Move Folder [PUT /folders/{folderPath}]
#### Delete Folder [DELETE /folder/{folderPath}]

Unfortunately a new commit seems to have broken this workaround. Were hoping that you might have a suggestion on how to document the current state of our api's whilst avoiding code changes to suit documentation.

pksunkara commented 9 years ago

Just to confirm, you are saying that this workaround broke due to the above linked apiaryio/snowcrash#337. If that is true, then we need to look into this and fix it. But this might be an apiary website related issue as shown in #245 .

zdne commented 9 years ago

@juniorleota 

### Folders [/folders]
#### Retrive FolderList [GET]
#### Create New Folder [POST]
#### Move Folder [PUT /folders/{folderPath}]
#### Delete Folder [DELETE /folder/{folderPath}]

Is the preferred way to do this in API Blueprint. Note there may be a bug in the way Apiary.io renders this as @pksunkara pointed out – see #245 – is this the case?

juniorleota commented 9 years ago

@pksunkara I am not sure, that referenced commit seems like it was modified in the right date. But it could be something else

@zdne A few days ago it would show #### retrieve folder properly within the side bar. In the side bar it only shows### folder and then renders folder for each action with a different Uri. But yeah in this scenario the sidebar provides no value and there is a lot of redundant information being rerendered for each action.

juniorleota commented 9 years ago

@zdne I modified our documentation as you suggested and it works. Thanks heaps :).

zdne commented 9 years ago

Great! Good to know @juniorleota ! thanks