Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for `summary` and `description` fields for paths #227

Closed
timakro opened this issue Jun 13, 2018 · 7 comments

Comments

@timakro
Copy link

commented Jun 13, 2018

Documented here:

Paths may have an optional short summary and a longer description for documentation purposes. This information is supposed to be relevant to all operations in this path. description can be multi-line and supports Markdown (CommonMark) for rich text representation.

@brunoais

This comment has been minimized.

Copy link

commented Jun 14, 2018

I don't get what you mean. What kind of support from apispec is needed for that?

@timakro

This comment has been minimized.

Copy link
Author

commented Jun 15, 2018

This check prevents you from using them.

@brunoais

This comment has been minimized.

Copy link

commented Jun 15, 2018

That check only checks for HTTP methods and not what you describe above.
What you describe above is nested inside the HTTP method

@timakro

This comment has been minimized.

Copy link
Author

commented Jun 15, 2018

summary and description are also allowed for paths:

    paths:
      /users/{id}:
        summary: Represents a user
        description: >
          This resource represents an individual user in the system.
          Each user is identified by a numeric `id`.
        get:
          ...
        patch:
          ...
        delete:
          ...
@brunoais

This comment has been minimized.

Copy link

commented Jun 15, 2018

Oh, right. I forgot about the 3rd version of the spec. I suppose they saw no one would use such as methods.
I hadn't notice it's here got it.

@sloria

This comment has been minimized.

Copy link
Member

commented Jun 18, 2018

Thanks for reporting @timakro .I would certainly review/merge a PR for this.

@lafrech

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

This could be done by passing those as add_path kwargs:

    def add_path(self, path=None, operations=None, **kwargs):
        [...]
        self._paths.setdefault(path, operations).update(operations)

        self._paths[path].update({attr: kwargs[attr] for attr in ('summary', 'description') if attr in kwargs})

This could conflict with plugin helpers using kwargs with the same name (unlikely).

User should be consistent if calling add_path several times for the same path.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.