docs icon indicating copy to clipboard operation
docs copied to clipboard

Published 20 hours ago • verified publisher icon api-platform

Configuration documentation reference

Open slavo2 opened this issue 5 years ago • 7 comments

Please, provide a configuration reference, with all possible fields and all of their reasonable settings and their meaning as well as examples.

slavo2 avatar Jul 11 '19 20:07 slavo2

Does this work for you? https://api-platform.com/docs/schema-generator/configuration/#full-configuration-reference

soyuka avatar Jul 16 '19 08:07 soyuka

Hi @soyuka Thank you for you reply, but not.

That link is a link to Schema Generator configuration.

  1. I suggest there would be a place of a full ApiPlatform documentation. https://api-platform.com/docs/core/configuration/#configuration could be a good start, but it would be good, if there would be all possible values and their effects explained and for the values, which are objects, that there would be reference to their possible keys, values and meaning.

  2. Also other configuration files, which affects how ApiPlatform works, would be nice to have documented here in similar way (or a separate documentation could be linked from here.)

  3. Moreover, It would be good if a a full reference of how API component may be used would existed (e.g. - when used with Annotations, what are all the possible keys and values for ApiResource, ApiFilter, ApiProperty... together with possible keys and values for their nested objects and so on.) It would be nice to have them all on one place, organized in a tree structure. This (3rd point) is however overlapping with this Issue -> https://github.com/api-platform/api-platform/issues/1117

slavo2 avatar Jul 17 '19 14:07 slavo2

In PHPStorm, 3. are documented via completion. If not, a quick look on the Annotation code source should do it! IDE today have quick navigation for this use case. Anyway, transfering to /docs.

soyuka avatar Feb 18 '20 10:02 soyuka

@Attribute("graphql", type="array") - "array" not very informative.

oleg-brizy avatar Feb 18 '20 10:02 oleg-brizy

A big 👍 on my side to add such reference document, for both annotations, XML and YAML. We could even generate it automatically from annotations (which list all available attributes).

dunglas avatar Feb 29 '20 11:02 dunglas

This is a must have. I don't get how the maintainers expect random users to create documentation for code they didn't write.

mnowaczyk avatar Sep 09 '20 15:09 mnowaczyk

This is such a must have for any good documentation (especially that API Platform is soooo configuration-driven). But I think it's either not really doable or would uncover a very inconvenient truth - annotation and yaml/xml support is sooo different:

See ApiResource config:

  • Annotations - https://github.com/api-platform/core/blob/master/src/Annotation/ApiResource.php#L25-L71
  • Yaml - https://github.com/api-platform/core/blob/master/src/Metadata/Extractor/YamlExtractor.php#L66-L74
  • Xml - https://github.com/api-platform/core/blob/master/src/Metadata/schema/metadata.xsd#L17-L33 or https://github.com/api-platform/core/blob/master/src/Metadata/Extractor/XmlExtractor.php#L45-L55

mkilmanas avatar Nov 06 '20 14:11 mkilmanas