Feature/apollo federation docs

[willwolfram18]

Summary

Updated the Hot Chocolate documentation to describe the Apollo Federation library.

• Documentation on creating an entity type
• Documentation on testing a [ReferenceResolver]
• Documentation on extending an entity type

Context

My team has been implementing an Apollo Federated GraphQL API using Hot Chocolate. As a way to help both my team and other developers in the community, I wanted to get the Apollo Federation documentation built out to help future developers take advantage of these tools within the framework.

I'm open to suggestions on content structure, or additional elements that should be included in the documentation, as I'm filling out information mostly from my experiences with the library at this point and I'm sure I don't know the whole set of capabilities the library has to offer yet.

[willwolfram18]

Since this is a WIP, and I'm not sure if the maintainers are notified of draft PRs, I want to tag @rstaib @michaelstaib @PascalSenn for some visibility.

Like I mentioned in the description, I'm definitely open to suggestions on content structure or additional sections or functionalities that are worth highlighting! Just lmk if you have any particular suggestions.

[michaelstaib]

cc @tobias-tengler

[michaelstaib]

Hey @willwolfram18 thank you for your help on this!

[tobias-tengler]

@willwolfram18 this looks great - thank you so much for chiming in! :)

I haven't explored the Apollo Federation integration yet, so I can't comment on what would be good to document.
I can however play the guinea pig and try to setup a working Apollo Federation integration going by your and Apollo's documentation. This should reveal if and where crucial information is missing on our side and I can do some editorial changes along the way.
Just ping me once you feel like it can be taken for a spin!

[willwolfram18]

@willwolfram18 this looks great - thank you so much for chiming in! :)

I haven't explored the Apollo Federation integration yet, so I can't comment on what would be good to document. I can however play the guinea pig and try to setup a working Apollo Federation integration going by your and Apollo's documentation. This should reveal if and where crucial information is missing on our side and I can do some editorial changes along the way. Just ping me once you feel like it can be taken for a spin!

Will do! I'm definitely onboard with having the doc pressure tested through application by another person! I am starting to wonder if it would be more helpful to structure this document as more of a "how to create a subgraph" docs, similar to Apollo Federation's docs: https://www.apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup/

I've flipped back and forth on whether it's more helpful to treat the document as a "hey, Apollo docs will give you all the details and know how of an Apollo subgraph works and we'll just tell you how to do it in Hot Chocolate" OR take a more thorough approach of saying "okay, start with creating 2 web API projects. Add your packages, define your types" and make it more step-by-step.

Any particular thoughts, one way or another? I'm starting to think that maybe a step-by-step is more helpful so that people know the specific steps they need to take and why

[tobias-tengler]

Hmm, I would assume most people wishing to create an Apollo Federation Subgraph in Hot Chocolate have experience with Apollo Federation. So I don't think we need to be super thorough and explain all the concepts.
I'd go for a step by step approach and just link to the Apollo docs in the intro.

[willwolfram18]

@tobias-tengler I think the docs are ready for a test drive when you're ready! I'm not familiar with the "contributing computed fields" portion of the API's functionality yet so I won't be able to fill that out but I'll make it a goal to work on that in a subsequent PR.

Would love whatever feedback you have to help make this easier to digest and understand, whether it be wording, level of detail, or general organization. Just want to see this become more helpful for others in the future!

Once the v12 doc is in a reasonable state, I'll copy the information over to the v13 so that we have a solid foundation to build out those docs with any changes since v12.6 👍

[tobias-tengler]

Thank you so much 🙏

I'll take it for a spin over the weekend!

[tobias-tengler]

This looks pretty good :) All in all I had no real trouble setting up two simple subgraphs, after reading this and Apollo's documentation.
I highlighted places that need some clarifications in my opinion.

There are also some Markdown formatting issues, like missing spaces after headings. If you use VS Code, you can resolve them by simply formatting the document (I think). The numbered lists all start with 1. as well :D

[tobias-tengler]

I think afterwards we could link to our Apollo Federation examples for folks that just want to look at a working setup: https://github.com/ChilliCream/graphql-platform/tree/main/src/HotChocolate/ApolloFederation/examples

[willwolfram18]

Love the suggestion! I think an additional contribution I'd like to make, if I can make the time, is setting up one or both of the solutions with a docker-compose.yaml file that would allow someone to easily spin up all of the subgraphs in one easy command. Pair that with the fact that Visual Studio has support for docker-compose.yaml and we can provide users with an easy "click once" style debugging session that can help them interact with the example and see the pieces working all together 👍

[willwolfram18]

This looks pretty good :) All in all I had no real trouble setting up two simple subgraphs, after reading this and Apollo's documentation. I highlighted places that need some clarifications in my opinion.

There are also some Markdown formatting issues, like missing spaces after headings. If you use VS Code, you can resolve them by simply formatting the document (I think). The numbered lists all start with 1. as well :D

Thanks for taking it for a test drive! I'll work on addressing those comments and the formatting issues. Also, as a quick note, I intentionally left all of the ordered lists as 1. because the markdown engine will automatically render the list with the proper order without needing to update each number. I've personally found this to be helpful when maintaining MD files because you don't need to remember to change your numbering if you move items around, and more naturally aligns to the <ol><li> syntax we'd use in HTML that don't require uses to specify ordering 👍

If it would be preferred to change to manual numbering, I can swap that, no issues for me 👍

[willwolfram18]

Hey @michaelstaib @tobias-tengler just checking in to see if this is ready to merge (aside from probably needing to merge latest changes from main into the working branch)

[yusufameri]

Hey @michaelstaib @tobias-tengler just checking in to see if this is ready to merge (aside from probably needing to merge latest changes from main into the working branch)

can you merge this? Looks like @tobias-tengler approved

[tobias-tengler]

I can't merge it. @michaelstaib needs to do it.

[tobias-tengler]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[willwolfram18]

/AzurePipelines run

[azure-pipelines]

Commenter does not have sufficient privileges for PR 5791 in repo ChilliCream/graphql-platform

[tobias-tengler]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[michael-watson]

👋 Is there anything I can do to help with these docs landing?

[tsinghammer]

@willwolfram18 I'm currently working on a PoC that uses Apollo's tutorial but replaces one of the subgraphs with a HC version.
It is working with both Federation packages, the one from Apollo and the official one from HotChocolate.
Would you like me to join in on the documentation? Ultimately we could extend the example and provide a repo with the full example.
I know that ChilliCream is focusing on Fusion but EF for instance is already using Apollo router, so it may be the only option to introduce HC @tobias-tengler

[tobias-tengler]

@tsinghammer my approval is there, but @michaelstaib needs to merge it - I can't.

[michaelstaib]

I will merge this version tonight.

[michaelstaib]

@tsinghammer I have merged it into main and you can do another PR and start on adding more documentation to it now.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information