Docs » Documenting your API_» Documenting responses from an endpoint Documenting responses from an endpoint It's helpful if your API's consumers can see what a response should be like before writing any code. There are multiple strategies to provide example responses for your endpoint: + describing the response using the eresponse tag + specifying a file containing the response using the éresponseFile tag + letting Scribe generate the response by making a “response call” + letting Scribe generate the response from the gapikesource tags (if you're using Eloquent API resources) + letting Scribe generate the response from the gcransformer tags (if you're using Transformers) You can use all of these strategies within the same endpoint. Scribe will display all the responses it finds. @response You can provide an example response for an endpoint by using the response annotation with valid JSON: uo * Gresponse { + oan: 4, * "name": "Jessica Jones”, * "roles": ["adnin"] +} v public function show(sid) t return User: :findorFail($id); >You can also specify a status code (otherwise 200 will be assumed): a * @response smd": 4, *) v You can define multiple possible responses from the same endpoint using gresponse . To distinguish th * @response «oat: 4 +} * Gresponse + "message +) ” 201 { “Jessica Jones” jese responses, you can use the status and scenario attributes. Jessica Jones" status=404 scenario="user not found” { ‘User not found’Ser eareeen eel estias=)) eee COC Maras CTT} To indicate a binary response, use <> as the value of the response, followed by a iption. SPIER ACU} CeCe) @responseFile @responseFile works similarly to @response , but instead of inlining the response, you pass a file containing your JSON response. This can be helpful if your response body is large,To use GresponseFile , place the response as a JSON string in a file somewhere in your project directory and specify the relative path to it. For instance, we can put this response in a file named users.get.json iN storage/responses/ {("id":4,"nane": "Jessica Jones") Then in the controller: uo * GresponseFile storage/responses/users.get.json ” public function getUser(int $id) £ us y OTip IF the file is in your Laravel storage directory, you can omit the storage/_ part from the file name. You can also have multiple gresponserite tags ona single method, distinguished by status code and/or scenarios. ao * GresponseFile responses/users.get.json * GresponseFile status=268 scenario="uhen authenticated as admin” responses/user. get-adnin. json * @responseFile status=4e4 responses/model..not. found. json v faresponseriie also allows you to overwrite parts of the response from the file with some data of your own. To do this, add the JSON you want to merge after the file path. For instance, supposing our generic “not found” response located in. storage/responses/nodel not.Found. json | SAYS: rype": “Model”, sult": “not found” We can change the type to user on the fly like this:"wien aut? .es/model.. not. This JSON string will be parsed and merged with the response from the file. ona He Se oe a ene Sos ee MCia ie ac tes} seers Generating responses automatically via response calls If you don't specify an example response using any of the other means described in this document, Scribe will attempt to get a sample response by making a HTTP request to the local endpoint (known as a “response call”)Response calls are done within a database transaction and changes are rolled back afterwards, so no data is persisted. If your database connection does not support transactions, you should add it to continue_without_database_transactions, but be warned that data from response calls will be persisted. The configuration for response calls is located in the appiy.response_calls section for each route group in config/seribe.php . This means that you can apply different settings for different sets of routes. Here are some important things to note: + By default, response calls are only made for cet routes, but you can configure this by setting the response_calis.nethods key to an array of methods (e.g. ['cer’, ‘vur') ).Setitto [+7 to mean all methods. Leave it as an empty array to turn off response calls for that route group. + You can specify Laravel config variables to be modified for the response call. This is useful so you can prevent external services like notifications from being triggered. By default the app.env is set to ‘documentation’, You can add more variables in the response_calls.config key. OTip You can also modify the environment directly by using a .env.docs_ file and running scribe:generate With --env docs + By default, the package will generate dummy values for your documented query, body and file parameters and send in the request. If you specified example values using @bodyearan or @queryParan , those will be used instead. You can configure additional parameters or overwrite the existing ones for the request in the | cesponse_calls.quesyParans | cesponse_calls.bodyParans 5 and response _calls.fileParans sections. For file parameters, each value should be a valid path (absolute or relative to your project directory) to a file on the machine. @Note If you specified No-example for a parameter earlier, it won't be included when making a response call. @ Note Unlike the other approaches described in this document, the Responsecalls strategy will only attempt to fetch a response if there are no responses with a status code of 2xx already. @apiResource , @apiResourceCollection , ANd @apiResourceModel If your endpoint uses Eloquent API resources to generate its response, you can use the @epikesource annotations to guide Scribe when generating a sample response. There are three available annotations:+ @apikesource , which specifies the name of the resource. + @apikesourcecolection , which should be used instead of @apiresource if the route returns a list, either via Yourkesource: :collection() OF new Yourkesourcecollection ). Here you'll specify the name of the resource or resource collection. + @apinesourcetodel , which specifies the Eloquent model to be passed to the resource. You should use gapinesourcetocel alongside either of the other two. Examples: a * @apiresource App\Resources\UserResource * GapiResourceodel App\ModeLs\User 7 public function showUser(User $user) { return new UserResource($user); y ne * @apinesourcecollection App\Resources\UserResource * @apiResourceodel. App\Models\User 7 public function 1istUsers() { return UserResource: :collection(User::al1()); y ” * @apiResourceCoLLection App\Resources\UserColLection * GopiResourceModel. App\NodeLs\User ” public function 1istMoreUsers() t return new UserCollection(User::a11())s » Scribe will generate an instance (or instances) of the model and pass the modells) to the resource transformer to get the example response. OTip To understand how Scribe generates an instance of your model and how you can customize that, you should check out the section on How model instances are generated. Paginating with API Resources If your endpoint returns a paginated response, you can tell Scribe how to paginate by using the paginate attribute on @apiresourceModel |oo * GopiResourceCoLlection App\Resources\UserColLection * GapiResourcelodel App\ModeLs\User paginate=10 v public function listMoreUsers() { return new UserCollection (User: :paginate(1@)); > no * GapikesourceCollection App\Resources\UserColLection * @qpiResourceModel App\NodeLs\User paginate=15, simple ” public function listMoreUsers() t return new UserCollection(User: :simplePaginate(15)); y @transformer, @transformerCollection, and @transformerModel If you're using transformers (via the league/fractal package), you can tell Scribe how to generate a sample response by using the transformer annotations. There are three available annotations: + @transformer , which specifies the name of the Transformer class. © @transformerCollection , which should be used instead of @transformer if the route returns a list. + @transformertodel , which specifies the Eloquent model to be passed to the transformer. You should use @transformerMocel alongside either of the other two. OTip Specifying @t-ansfornertode1 is optional. If you don't specify it, Scribe will attempt to use the class of the first parameter to the transformer's | transforn() method. For example: a * @transformer App\Transformers\UserTransformer * @transformerModel. App\Models\User 7 public function showUser(int $id) t “us y or * @transformerCoLLection App\Iransformers\UserTransformer + @transformerModel. App\NodeLs\User 7 public function listUsers() « Mo yScribe will generate an instance (or instances) of the model and pass the model(s) to the transformer to get the example response. OTip To understand how Scribe generates an instance of your model and how you can customize that, you should check out the section on How model instances are generated. If your response data is nested within a Fractal resource key, you can specify it via an additional attribute in the @transformerModel tag. ao * @transformer App\Transformers\UserTronsformer * @transformertodel App\Models\User resourceKey=user v Paginating with transformers If your endpoint uses a paginator with the transformer, you can tell Scribe how to paginate via an additional tag, @tcansfornerPaginato> a * @transformerCollection App\Transformers\UserTransformer * @transformerHodel App\ModeLs\User * @transformerPaginator League\Fractal \Pagination\ILLuminatePaginatorAdapter 15 ” public function 1istMoreUsers() £ $paginator = User: :paginate(15); $users = $paginator->getCollection(); $transformer = new Fractal\Resource\Collection($users, new UserTransformer(), ‘data"); $transformer->setPaginator(new ILluminatePaginatorAdapter (Susers)); return $fractal-»createbata($users)->toarray(); How model instances are generated When generating responses from @apikesource and @transformer tags, Scribe needs to generate a sample model to pass to the resource or transformer. Here's the process Scribe follows: 1. First, it tries the Eloquent model factory: Factory(Yourtodel::class)-rereate() « @ Note Scribe uses create() instead of make() when calling the factory, but runs it in a database transaction which is rolled back afterwards, so no data is persisted. If your database connection does not support transactions, you should add it tocontinue_without_database_transactions, but be warned that created models will be persisted. 1. If that fails, Scribe calls vourvoce:::first() to retrieve the first model from the database. 2. If that fails, Scribe creates an instance using. new Yourtiodel() « Applying factory states If you want specific states to be applied to your model when instantiating via the Laravel model factory, you can use the states attribute on @apikesourceodel OF ftransformertodel . Separate multiple states with a comma ao * @apiResourceCoLLection App\Resources\UserCollection * GapiResourceltodel App\ModeLs\User states=student, verified v Loading specific relations If you want specific relations to be loaded with your model when instantiating via YourModel::First() | YOu can use the with attribute on gapiResourcerodel OF @transfornerModel « Separate multiple relations with a comma. ao * @apiResourceCoLLection App\Resources\UserCoLLection * GapiResourceltodel App\ModeLs\User with=teacher, classmates v Adding descriptions for fields in the responses You can add descriptions for fields in your response by adding a gresponseField annotation to your controller method. oa * GresponseField id The id of the newly created word vy Scribe figures out the type of the field from the 2xx responses for that endpoint. OTip You don't need to specify the full field path if the field is inside an array of objects or wrapped in pagination data. For instance, the above annotation will work fine for all of these responses:{ "id": 3} c ("ish 3)Example response (200): you can also specify the type of the parameter: