Is there any way to define descriptions & examples

[netdjw]

Is there any way to define descriptions & examples in routes, models, controllers or rules?

I get this YAML output, what is excellent:

  /api/member/user/create:
    post:
      description: POST /api/member/user/create
      responses:
        200:
          description: OK
      parameters:
      - in: body
        name: body
        description: ""
        schema:
          type: object
          required:
          - lang_id
          - name
          - user
          - password
          - email
          - is_inactive
          properties:
            lang_id:
              type: integer
            name:
              type: string
            user:
              type: string
            password:
              type: string
            email:
              type: string
            is_inactive:
              type: boolean

But if I upgrade my code (routes, models, etc.) and regenerate this YAML file, all my modify gone. If I can define descriptions & examples between my code lines it can be prevent this issue and would be more handy.

Is this possible?

[mtrajano]

Hey thank you so much for the suggestions if you want to take a stab at this, feel free to submit a pr. If not I’ll try to get something out for this over the weekend. Thanks!

[netdjw]

I started to study your code, but I don't have too much time between projects. If I can step forward I will send a pull request of course. And thank you for this great stuff :) You saved me many times and help debug our codes :)

[mtrajano]

Hi @netdjw just an update to this. I added the ability to parse your action methods docBlock for any text that is not an annotation line and this will be added as your route's description. Let me know if this works well for your application or if you face any issues with it, feedback is appreciated! Closing the issue for now, feel free to reopen if you can think of a new way to implement this feature or if you come across any issues with it.