MB-9620-edit-enpoint-docs #12

NamibiaTorres · 2021-10-06T01:14:50Z

The purpose of this PR is to update the Endpoint documentation in Docusaurus with more detailed information (i.e. steps to creating an endpoint) and technical examples.

Feedback request

I'd like to add more context to the event maps section at the end. What information would be most useful to put in this section.

For the "How to handle errors" section is this the right place for this info or should we create a separate document for that? If so, I can add a template for that document and work on it while on A Team.

Other info

jira ticket

eamahanna · 2021-10-06T13:55:51Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+# Creating an Endpoint
+###### These are the various steps that are involved in creating a new endpoint.
+
+Prior to creating adding an endpoint to the Handler folder, we must first add a new endpoint definition to swagger. We are using Swagger 2.0, which is [OpenAPI](https://swagger.io/specification/v2/), a specification we use to format our RESTful APIs and provide a template for us to communicate the information in our API.


creating adding, typo

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

eamahanna · 2021-10-06T14:00:08Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+###### These are the various steps that are involved in creating a new endpoint.
+
+Prior to creating adding an endpoint to the Handler folder, we must first add a new endpoint definition to swagger. We are using Swagger 2.0, which is [OpenAPI](https://swagger.io/specification/v2/), a specification we use to format our RESTful APIs and provide a template for us to communicate the information in our API.
+Always start with swagger. This step creates your endpoint definition and generates the files and helper functions you will need to create your endpoint. More specifically, swagger converts JSON user input into generated Go types.


Can you add the link to the documentation that discusses the mock files?

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

eamahanna · 2021-10-06T14:09:04Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+              availableToPrimeAt:
+                format: date-time
+                type: string
+                x-nullable: true


It may be good to highlight that for any nullable field we need to use

x-nullable: true x-omitempty: false

This will return null in the response if the value doesn't exist. If we didn't all this, the field would be omitted.

Oh yes! I agree it's important to mention that the field will be omitted otherwise.

It may be good to highlight that for any nullable field we need to use

x-nullable: true x-omitempty: false

This will return null in the response if the value doesn't exist. If we didn't all this, the field would be omitted.

I'm adding the field about the field being ommitted to this line on line 69:

x-nullable - this indicates that the value of a particular property may be null.

I also added a new bullet point and description for x-omitempty.

eamahanna · 2021-10-06T14:09:43Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+
+#### Gen files:
+Once you finishing updating the yaml files with the new endpoint information make sure to run your make commands to autogenerate your swagger files, or simply run `make server_run`, 
+which runs your server and other useful make commands in one go.


Can you add you may need to run make swagger-generate

It may also be helpful to add a Troubleshooting section here so that folks can fix their local Swagger state if they get stuck. Here's the Slack conversation that documents this now.

eamahanna · 2021-10-06T14:10:15Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+Once you finishing updating the yaml files with the new endpoint information make sure to run your make commands to autogenerate your swagger files, or simply run `make server_run`, 
+which runs your server and other useful make commands in one go.
+
+## Creating an endpoint. 


You may want to rename this section Creating a Handler

eamahanna · 2021-10-06T14:44:27Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+
+
+#### How to handle errors
+TODO: WIP


I believe we have documentation for errors: https://github.com/transcom/mymove-docs/blob/720592c63db4bffe402a801417f7c14772573c28/docs/dev/contributing/backend/API-Errors.md

Great! I'll just like to that. It felt like this should be a separate doc anyways.

eamahanna · 2021-10-06T14:45:30Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+#### How to handle errors
+TODO: WIP
+### Add event key and update event map
+Each API has a corresponding file in `/pkg/services/event/<apiName>_endpoint.go`


you can also link to https://github.com/transcom/mymove-docs/blob/720592c63db4bffe402a801417f7c14772573c28/docs/dev/contributing/backend/How-to-Add-an-Event-Trigger.md

rogeruiz

This is only part 1️⃣ of my review @NamibiaTorres but I am submitting as a comment so I don't stop this from getting merged in. Great work on this 🎉 . I think it's going to be super helpful to have this type of breakdown in our documentation.

My concerns here is that maybe some of this documentation would be better suited as examples similar to the work in the other PR transcom/mymove#7435. But I'm including some of my comments here so they don't get lost.

rogeruiz · 2021-10-06T15:13:05Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+        /your path:
+            HTTP request:
+                summary:
+                description:


This section will eventually need to be refactored to something like this after transcom/mymove#7435 is merged into the default branch over on that repo.

Suggested change

description:

description:

$ref: 'info/{file_name}.md'

I appreciate the breakdown here, but since this type of documentation must stay in sync with the way the Swagger files are written in the other repository I'm worried that it's double the effort to make sure this Yaml structure is kept up to date with how the Swagger files are maintained.

cc: @scarequotes for their opinion on where this type of documentation is more appropriate.

I see, and agree, we definitely want to push folks to started using our new way of writing descriptions.

rogeruiz · 2021-10-06T15:15:24Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+          description: |
+            Gets all moves that have been reviewed and approved by the TOO. 


Same as the description block above. Once the work I've started in transcom/mymove#7435 is finalized and merged in, this will need to be updated to something like the suggestion below.

Suggested change

description: |

Gets all moves that have been reviewed and approved by the TOO.

description:

$ref: 'info/prime_listMoves.md'

rogeruiz · 2021-10-06T15:18:44Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+            description: >
+              An abbreviated definition for a move, without all the nested information (shipments, service items, etc). Used to
+              fetch a list of moves more efficiently.


Looking at how the documentation is written here, I'm starting to think that with transcom/mymove#7435 we can update this documentation page to say something along the lines of

Make sure the description: file is pointing to a Markdown file in the swagger-def/info directory contains the description of the endpoint.

Relevant but redundant comment because this documentation is similar to the documentation above.

Same as the description block above. Once the work I've started in transcom/mymove#7435 is finalized and merged in, this will need to be updated to something like the suggestion below.

Suggested change

description: >

An abbreviated definition for a move, without all the nested information (shipments, service items, etc). Used to

fetch a list of moves more efficiently.

description:

$ref: 'info/prime_listMoves.md'

rogeruiz · 2021-10-06T15:20:35Z

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md

+
+#### Gen files:
+Once you finishing updating the yaml files with the new endpoint information make sure to run your make commands to autogenerate your swagger files, or simply run `make server_run`, 
+which runs your server and other useful make commands in one go.


It may also be helpful to add a Troubleshooting section here so that folks can fix their local Swagger state if they get stuck. Here's the Slack conversation that documents this now.

NamibiaTorres added 3 commits October 5, 2021 17:00

update endpoint docs

d57952d

Add new example

80e42fd

Add note

ea324e5

NamibiaTorres requested review from rogeruiz, eamahanna and pmohal October 6, 2021 01:14

Edit doc

6a1edb6

NamibiaTorres requested a review from leia-sefkin October 6, 2021 01:21

eamahanna reviewed Oct 6, 2021

View reviewed changes

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md Show resolved Hide resolved

eamahanna reviewed Oct 6, 2021

View reviewed changes

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md Outdated Show resolved Hide resolved

eamahanna reviewed Oct 6, 2021

View reviewed changes

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md Show resolved Hide resolved

eamahanna reviewed Oct 6, 2021

View reviewed changes

docs/dev/contributing/backend/Guide-to-Creating-an-Endpoint.md Outdated Show resolved Hide resolved

eamahanna reviewed Oct 6, 2021

View reviewed changes

rogeruiz reviewed Oct 6, 2021

View reviewed changes

NamibiaTorres added 2 commits October 6, 2021 10:19

incorporate feedback into new edits

da56c52

incorporate feedback into new edits

84b3f42

NamibiaTorres requested review from eamahanna and rogeruiz October 6, 2021 18:03

eamahanna approved these changes Oct 6, 2021

View reviewed changes

NamibiaTorres merged commit c08ae4d into main Oct 7, 2021

NamibiaTorres deleted the MB-9620-edit-enpoint_docs branch October 7, 2021 19:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MB-9620-edit-enpoint-docs #12

MB-9620-edit-enpoint-docs #12

NamibiaTorres commented Oct 6, 2021 •

edited

Loading

eamahanna Oct 6, 2021

eamahanna Oct 6, 2021

eamahanna Oct 6, 2021

NamibiaTorres Oct 6, 2021

NamibiaTorres Oct 6, 2021 •

edited

Loading

eamahanna Oct 6, 2021

rogeruiz Oct 6, 2021

eamahanna Oct 6, 2021

eamahanna Oct 6, 2021

NamibiaTorres Oct 6, 2021

eamahanna Oct 6, 2021

rogeruiz left a comment

rogeruiz Oct 6, 2021

NamibiaTorres Oct 6, 2021

rogeruiz Oct 6, 2021

rogeruiz Oct 6, 2021

rogeruiz Oct 6, 2021

		description: \|
		Gets all moves that have been reviewed and approved by the TOO.

MB-9620-edit-enpoint-docs #12

MB-9620-edit-enpoint-docs #12

Conversation

NamibiaTorres commented Oct 6, 2021 • edited Loading

Feedback request

Other info

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NamibiaTorres Oct 6, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rogeruiz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NamibiaTorres commented Oct 6, 2021 •

edited

Loading

NamibiaTorres Oct 6, 2021 •

edited

Loading