Ce diaporama a bien été signalé.
Le téléchargement de votre SlideShare est en cours. ×

GraphQL Isn't An Excuse To Stop Writing Docs

Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Prochain SlideShare
API Documentation For Web3
API Documentation For Web3
Chargement dans…3
×

Consultez-les par la suite

1 sur 66 Publicité

GraphQL Isn't An Excuse To Stop Writing Docs

Télécharger pour lire hors ligne

The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this?

Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL. But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This talk explores which forms of documentation you can use and how they add value to your GraphQL API.

The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this?

Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL. But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This talk explores which forms of documentation you can use and how they add value to your GraphQL API.

Publicité
Publicité

Plus De Contenu Connexe

Plus par Pronovix (20)

Plus récents (20)

Publicité

GraphQL Isn't An Excuse To Stop Writing Docs

  1. 1. Roy Derks @gethackteam GraphQL Is No Excuse To Stop Writing Docs
  2. 2. @gethackteam What is documentation?
  3. 3. @gethackteam
  4. 4. @gethackteam A little bit about myself fi rst…
  5. 5. Roy Derks @gethackteam Hey! I'm Roy an entrepreneur and software engineer, author and public speaker from The Netherlands. + more @gethackteam
  6. 6. @gethackteam What is documentation?
  7. 7. @gethackteam Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use. - the internet
  8. 8. @gethackteam Documentation is communicable material (1/2)
  9. 9. @gethackteam
  10. 10. @gethackteam
  11. 11. @gethackteam Or for GraphQL
  12. 12. @gethackteam
  13. 13. @gethackteam Let’s give it up for the GraphiQL team 👏👏
  14. 14. @gethackteam Documentation could be both static and dynamic
  15. 15. @gethackteam Documentation could be both static and dynamic
  16. 16. @gethackteam Documentation could be both static and dynamic - API Playgrounds - Code examples - GraphiQL
  17. 17. @gethackteam Documentation is used to describe, explain or instruct (2/2)
  18. 18. @gethackteam 1. describe 2. explain 3. instruct
  19. 19. @gethackteam 1. describe 2. explain 3. instruct
  20. 20. @gethackteam describe List of attributes: API reference SDK reference …
  21. 21. @gethackteam 1. describe 2. explain 3. instruct
  22. 22. @gethackteam explain Explain concepts, procedures or
  23. 23. @gethackteam 1. describe 2. explain 3. instruct
  24. 24. @gethackteam instruct Instruct on installation, usage or maintenance
  25. 25. @gethackteam How are GraphQL APIs usually documented?
  26. 26. @gethackteam First, a hard question
  27. 27. @gethackteam Is GraphQL really self-documenting?
  28. 28. introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql @gethackteam
  29. 29. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql GraphiQL * OPTIONAL
  30. 30. @gethackteam Is GraphQL really self-documenting?
  31. 31. @gethackteam Only up to a small amount
  32. 32. @gethackteam The power is in the schema and introspection
  33. 33. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql
  34. 34. @gethackteam Introspection exposes your GraphQL schema
  35. 35. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql GraphiQL
  36. 36. @gethackteam And can be used by tools like GraphiQL
  37. 37. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql GraphiQL
  38. 38. @gethackteam There are similar tools like GraphiQL
  39. 39. @gethackteam GraphQL Playground, Apollo Studio, GraphQL Editor, …
  40. 40. @gethackteam But are these tools enough?
  41. 41. Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use. - the internet @gethackteam
  42. 42. Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use. - the internet @gethackteam
  43. 43. @gethackteam GraphiQL Describe ✅ Explain Instruct
  44. 44. @gethackteam GraphiQL Describe ✅ Explain Instruct ✅
  45. 45. @gethackteam Describe ✅ Explain? Instruct ✅
  46. 46. @gethackteam Description OR Explanation?
  47. 47. @gethackteam """ Multiline description of the User type """ type Customer { address: Address email: String id: Int # Unique identifier of the customer in a single line name: String } type Query { """ Will return a list of customers More info in our documentation """ getCustomerList: [Customer] getCustomerById(id: ID!): Customer } Schema annotations
  48. 48. @gethackteam """ Multiline description of the User type """ type Customer { address: Address email: String id: Int # Unique identifier of the customer in a single line name: String } type Query { """ Will return a list of customers More info in our documentation """ getCustomerList: [Customer] getCustomerById(id: ID!): Customer } Schema annotations
  49. 49. @gethackteam GraphiQL (and others) lack in-depth explain features
  50. 50. @gethackteam What are we missing? - Installation - Authentication - Troubleshoot - …
  51. 51. @gethackteam Earlier we learned: Documentation could be both static and dynamic
  52. 52. @gethackteam GraphiQL is mostly dynamic, but lacks space for explanations
  53. 53. @gethackteam Space we need for text, graphics and videos
  54. 54. @gethackteam To explain how the GraphQL API works in-depth
  55. 55. @gethackteam And we can use introspect to bootstrap it
  56. 56. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql
  57. 57. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql GraphiQL
  58. 58. @gethackteam introspection type Customer { address: Address email: String id: Int name: String } type Query { getCustomerList: [Customer] getCustomerById(id: ID!): Customer } schema curl -X POST -H "Content-Type: application/json" -d '{"query": "{ __schema { queryType { name } }"}' https://my.graphql.server/graphql GraphiQL Static docs
  59. 59. @gethackteam There are plenty of static documentation generators
  60. 60. Magidoc SpectaQL @gethackteam DociQL
  61. 61. @gethackteam They let you extend the introspected docs with text, markdown, and JS
  62. 62. @gethackteam So we can explain: - Installation - Authentication - Troubleshoot - …
  63. 63. @gethackteam GraphiQL Static docs GraphQL Documentation
  64. 64. @gethackteam GraphiQL Static docs GraphQL Documentation Describe ✅ Explain Instruct ✅ Describe ✅ Explain ✅ Instruct
  65. 65. @gethackteam GraphiQL Static docs GraphQL Documentation ❤ 🚀
  66. 66. Roy Derks @gethackteam Thank you! Let’s stay in touch stepzen.com hackteam.io

×