knuckleswtf / knuckleswtf/scribe

@urlParam not overriding ID parameters

Open
#873 2 comments 1 reaction 0 assignees View on GitHub
bug triage
Dominant language
PHP
Stars
2.3k
Forks
357
PR merge metrics
No merged PRs in 30d

Description

### Scribe version

4.37.1

### PHP version

8.3

### Framework

Laravel

### Framework version

11.15.0

### Scribe config

```ruby
type => "external_static"
theme => "scalar"
try_it_out.use_csrf => true
postman.enabled => false
```

### What happened?

I attempted to add the `@urlParam` comment for an ID field where the primary key is a column other than ID (called 'Symbol'), and it did not override the generated documentation contrary to what is explained in Scribe's documentation here: https://scribe.knuckles.wtf/laravel/documenting/url-parameters

Screenshot 2024-07-22 at 7 12 57 PM

My route is as follows:

`Route::get('/symbol/{symbol}/{interval}/{startDate}/{endDate}', [SymbolController::class, 'show']);`

My comment above the show function is as follows:

`@urlParam symbol string required The symbol ticker to get data for (case-sensitive) Example: AAPL`

But instead of displaying my custom description in the generated documentation, it lists 'symbol_Symbol' as the parameter and has no description. I can override the description by changing the comment to `@urlParam symbol_Symbol string required The symbol ticker to get data for (case-sensitive) Example: AAPL` to match what is being generated, but I want the parameter to be correctly labelled `symbol` rather than `symbol_Symbol`.

Other than that this is a great tool, thank you developers!

### Docs

- [X] I've checked [the docs](https://scribe.knuckles.wtf/laravel), the [troubleshooting guide](https://scribe.knuckles.wtf/laravel/troubleshooting), and [existing issues](https://github.com/knuckleswtf/scribe/issues?q=is%3Aissue+), but I didn't find a solution

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue with the documented Laravel route, the Symbol primary-key setup, and the show method's @urlParam symbol annotation. Compare the generated parameter with the annotation and the URL-parameter documentation; done means the generated docs label the parameter symbol and retain its custom description.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, php
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.