Change Details

"As a Client Developer, I want to download a machine-readable definition of the API, so I can generate tools or documentation from it." This is somewhat teased out from {T236113}, which is about automated documentation generation. One way to do that is to use a standard API definition language like [[ https://swagger.io/docs/specification/about/ | OpenAPI ]] or [[ https://raml.org/ | RAML ]] to define the API, and then using off-the-shelf or custom text generators to create the documentation from that definition. But it's not the //only// way. There are some benefits to having a machine readable definition of the API: - Automatic building of client-side libraries for the API (although these usually aren't great libraries) - Automatic documentation in different formats - Integration with IDEs, linters, or other automated development tools There are a number of [[ https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages | languages used for API descriptions ]]. OpenAPI seems to be the main one used right now, but there might be a case to be made for other languages instead of, or in addition to, OpenAPI.

"As a Client Developer, I want to download a machine-readable definition of the API, so I can generate tools or documentation from it." This is somewhat teased out from {T236113}, which is about automated documentation generation. One way to do that is to use a standard API definition language like [[ https://swagger.io/docs/specification/about/ | OpenAPI ]] or [[ https://raml.org/ | RAML ]] to define the API, and then using off-the-shelf or custom text generators to create the documentation from that definition. But it's not the //only// way. There are other benefits to having a machine readable definition of the API, though, which make it a separate user story: - Automatic building of client-side libraries for the API (although these usually aren't great libraries) - Automatic documentation in different formats - Integration with IDEs, linters, or other automated development tools There are a number of [[ https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages | languages used for API descriptions ]]. OpenAPI seems to be the main one used right now, but there might be a case to be made for other languages instead of, or in addition to, OpenAPI.

"As a Client Developer, I want to download a machine-readable definition of the API, so I can generate tools or documentation from it." This is somewhat teased out from {T236113}, which is about automated documentation generation. One way to do that is to use a standard API definition language like [[ https://swagger.io/docs/specification/about/ | OpenAPI ]] or [[ https://raml.org/ | RAML ]] to define the API, and then using off-the-shelf or custom text generators to create the documentation from that definition. But it's not the //only// way. There are someother benefits to having a machine readable definition of the API, though, which make it a separate user story: - Automatic building of client-side libraries for the API (although these usually aren't great libraries) - Automatic documentation in different formats - Integration with IDEs, linters, or other automated development tools There are a number of [[ https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages | languages used for API descriptions ]]. OpenAPI seems to be the main one used right now, but there might be a case to be made for other languages instead of, or in addition to, OpenAPI.