Skip to content

Updated documentation to make it more useful #451

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 28, 2022
Merged

Updated documentation to make it more useful #451

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/gettingstarted/broadcast_data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ nav_order: 4

## Additional info

- Key Concepts: [Broadcast / shared data](/keyconcepts/broadcast.html)
- Swagger: [POST /api/v1/namespaces/{ns}/broadcast/message](/swagger/swagger.html#/default/postBroadcastMessage)
- Key Concepts: [Broadcast / shared data](/firefly/keyconcepts/broadcast.html)
Copy link
Contributor

@peterbroadhurst peterbroadhurst Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This broke the link for me on a local build of the docs, using the instructions here:
https://github.com/hyperledger/firefly/blob/main/docs/contributors/docs_setup.md#build-and-serve-the-docs-locally

However, I agree the main site is broken. So I think the issue here might be the local build instructions need to have a /firefly prefix somehow so that authors can test their changes correctly.

Copy link
Contributor

@peterbroadhurst peterbroadhurst Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've raised #461 for that issue @nickgaski - hopefully that helps you with the review on this one.

- Swagger: [POST /api/v1/namespaces/{ns}/broadcast/message](/firefly/swagger/swagger.html#/default/postBroadcastMessage)

## Example 1: Inline string data

Expand Down
2 changes: 1 addition & 1 deletion docs/gettingstarted/custom_blockchain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,4 +24,4 @@ those transactions in your application, are currently under development.
You can access the APIs of the blockchain interface plugins directly, which perform the heavy lifting
to add an API/Event gateway in front of the low level blockchain RPC interfaces.

See [Key Concepts: Blockchain protocols](/keyconcepts/blockchain_protocols.html) for more information.
See [Key Concepts: Blockchain protocols](/firefly/keyconcepts/blockchain_protocols.html) for more information.
4 changes: 2 additions & 2 deletions docs/gettingstarted/define_datatype.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ of datatypes, as is used to broadcast the data itself.

## Additional info

- Key Concepts: [Broadcast / shared data](/keyconcepts/broadcast.html)
- Swagger: [POST /api/v1/namespaces/{ns}/broadcast/datatype](/swagger/swagger.html#/default/postBroadcastDatatype)
- Key Concepts: [Broadcast / shared data](/firefly/keyconcepts/broadcast.html)
- Swagger: [POST /api/v1/namespaces/{ns}/broadcast/datatype](/firefly/swagger/swagger.html#/default/postBroadcastDatatype)

### Example 1: Broadcast new datatype

Expand Down
2 changes: 1 addition & 1 deletion docs/gettingstarted/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ We focus on WebSockets in this getting started guide.

## Additional info

- Key Concepts: [Multi-party process flow](/keyconcepts/multiparty_process_flow.html)
- Key Concepts: [Multi-party process flow](/firefly/keyconcepts/multiparty_process_flow.html)
- Reference: _coming soon_

## WebSockets Example 1: Ephemeral subscription with auto-commit
Expand Down
15 changes: 11 additions & 4 deletions docs/gettingstarted/private_send.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ nav_order: 4

## Additional info

- Key Concepts: [Private data exchange](/keyconcepts/data_exchange.html)
- Swagger: [POST /api/v1/namespaces/{ns}/send/message](/swagger/swagger.html#/default/postSendMessage)
- Key Concepts: [Private data exchange](/firefly/keyconcepts/data_exchange.html)
- Swagger: [POST /api/v1/namespaces/{ns}/send/message](/firefly/swagger/swagger.html#/default/postSendMessage)

## Example 1: Pinned private send of in-line string data

Expand Down Expand Up @@ -225,7 +225,7 @@ and pipe it into a multi-part form post to FireFly.
```sh
curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \
| curl --form autometa=true --form file=@- \
http://localhost:5000/api/v1/api/v1/namespaces/default/data
http://localhost:5000/api/v1/namespaces/default/data
```

### Example data response from BLOB upload
Expand Down Expand Up @@ -267,6 +267,13 @@ Just include a reference to the `id` returned from the upload.
{
"id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8"
}
]
],
"group":{
"members": [
{
"identity":"org_1"
}
]
}
}
```
4 changes: 2 additions & 2 deletions docs/gettingstarted/query_messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ This builds on the APIs to query and filter messages, described below

## Additional info

- Reference: [API Query Syntax](/reference/api_query_syntax.html)
- Swagger: [GET /api/v1/namespaces/{ns}/messages](/swagger/swagger.html#/default/getMsgs)
- Reference: [API Query Syntax](/firefly/reference/api_query_syntax.html)
- Swagger: [GET /api/v1/namespaces/{ns}/messages](/firefly/swagger/swagger.html#/default/getMsgs)

### Example 1: Query confirmed messages

Expand Down
2 changes: 1 addition & 1 deletion docs/keyconcepts/data_exchange.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ characteristics that differ between different implementations.
- There are many technologies including Mutual TLS, and Java Web Tokens (JWT),
that can be used to ensure a private data exchange is happening with the
correct party in the system.
- Most modern approaches us public/private key encryption to establish the identity
- Most modern approaches use public/private key encryption to establish the identity
during the setup phase of a connection. This means a distribution mechanism is required
for public keys, which might be enhanced with a trust hierarchy (like PKI).
- Request/Response (Sync) vs. Message Queuing (Async)
Expand Down
2 changes: 1 addition & 1 deletion docs/swagger/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10965,4 +10965,4 @@ paths:
default:
description: ""
servers:
- url: http://localhost:12345
- url: http://localhost:5000
Copy link
Contributor

@nguyer nguyer Feb 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is auto-generated, so the next time someone runs make swagger this will be overwritten. There is also a check to make sure that the file that is checked in to Git matches what the code would generate, and this is the check that's currently failing, blocking this from merging.

I think we can change this port to 5000, but it would just need to be changed in the swagger generator code, rather than in the auto-generated file.

Copy link
Contributor

@awrichar awrichar Feb 10, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the make swagger command actually just runs some specific unit tests. I suspect that these instances would need to change in order to update the port:

internal/apiserver/swagger_check_test.go:       handler := as.apiWrapper(as.swaggerHandler(as.swaggerGenerator(routes, "http://localhost:12345")))
internal/apiserver/swagger_generate_test.go:    handler := as.apiWrapper(as.swaggerHandler(as.swaggerGenerator(routes, "http://localhost:12345")))