Module readme
ballerinax/readme Ballerina library
1.5.2
Overview
The Readme API v2.0 connector(https://docs.readme.com/reference) OpenAPI specification.
The Readme API provides the capability to create product and API documentation programmatically.
Key Features
- Programmatic access to create and manage resources via REST API
- Manage user accounts and profiles
- Secure authentication with API key or OAuth support
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create a Readme account.
- Obtain tokens - Follow this guide.
Quickstart
To use the Readme connector in your Ballerina application, update the .bal file as follows:
Step 1: Import connector
First, import the ballerinax/readme module into the Ballerina project.
import ballerinax/readme;
Step 2: Create a new connector instance
You can now make the connection configuration using the Readme API keys config.
http:CredentialsConfig & readonly authConfig = ?; readme:ClientConfig clientConfig = {auth : authConfig}; readme:Client readmeClient = check new (clientConfig);
Step 3: Invoke connector operation
Following is code demonstrates how to get a project using ballerinax/readme connector.
public function main() returns error? { http:Response entity = check readmeClient->getProject(); }
Clients
readme: Client
Isolated
This is a generated connector for Readme API v2.0 OpenAPI specification.
The Readme API provides the capability to create product and API documentation programmatically.
Constructor
Gets invoked to initialize the connector.
The connector initialization requires setting the API credentials.
Create a Readme account and obtain tokens by following this guide.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://dash.readme.io/api/v1" - URL of the target service
getProject
Isolated FunctionRemote Function
Get metadata about the current project
getAPISpecification
Isolated FunctionRemote Function
Get API specification metadata
Parameters
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
- perPage int (default 10) - Number of items to include in pagination (up to 100, defaults to 10)
- page int (default 1) - Used to specify further pages (starts at 1)
uploadAPISpecification
Isolated FunctionRemote Function
Upload an API specification to ReadMe. Or, to use a newer solution see https://docs.readme.com/guides/docs/automatically-sync-api-specification-with-github
Parameters
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
- payload File - File
updateAPISpecification
Isolated FunctionRemote Function
Update an API specification in ReadMe
Parameters
- id string - ID of the API specification. The unique ID for each API can be found by navigating to your API Definitions page.
- payload File - File
deleteAPISpecification
Isolated FunctionRemote Function
Delete an API specification in ReadMe
Parameters
- id string - ID of the API specification. The unique ID for each API can be found by navigating to your API Definitions page.
getCategory
Isolated FunctionRemote Function
Get category
Parameters
- slug string - Slug of category. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the the category "Getting Started", enter the slug "getting-started"
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
getCategoryDocs
Isolated FunctionRemote Function
Get docs for category
Parameters
- slug string - Slug of category. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the the category "Getting Started", enter the slug "getting-started"
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
getChangelogs
Isolated FunctionRemote Function
Get changelogs
Parameters
- perPage int (default 10) - Number of items to include in pagination (up to 100, defaults to 10)
- page int (default 1) - Used to specify further pages (starts at 1)
createChangelog
Isolated FunctionRemote Function
Create changelog
Parameters
- payload Changelog - Changelog object
getChangelog
Isolated FunctionRemote Function
Get changelog
Parameters
- slug string - Slug of changelog
updateChangelog
Isolated FunctionRemote Function
Update changelog
deleteChangelog
Isolated FunctionRemote Function
Delete changelog
Parameters
- slug string - Slug of changelog
getCustomPages
Isolated FunctionRemote Function
Get custom pages
Parameters
- perPage int (default 10) - Number of items to include in pagination (up to 100, defaults to 10)
- page int (default 1) - Used to specify further pages (starts at 1)
createCustomPage
Isolated FunctionRemote Function
function createCustomPage(CustomPage payload) returns Response|errorCreate custom page
Parameters
- payload CustomPage - CustomPage object
getCustomPage
Isolated FunctionRemote Function
Get custom page
Parameters
- slug string - Slug of custom page
updateCustomPage
Isolated FunctionRemote Function
function updateCustomPage(string slug, CustomPage payload) returns Response|errorUpdate custom page
deleteCustomPage
Isolated FunctionRemote Function
Delete custom page
Parameters
- slug string - Slug of custom page
createDoc
Isolated FunctionRemote Function
Create doc
Parameters
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
- payload Doc - Doc object
searchDocs
Isolated FunctionRemote Function
Search docs
Parameters
- search string - Search string to look for
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
getDoc
Isolated FunctionRemote Function
Get doc
Parameters
- slug string - Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
updateDoc
Isolated FunctionRemote Function
Update doc
Parameters
- slug string - Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
- payload Doc - Doc object
deleteDoc
Isolated FunctionRemote Function
Delete doc
Parameters
- slug string - Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
- xReadmeVersion string - Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
getErrors
Isolated FunctionRemote Function
Get errors
deleteSwagger
DeprecatedIsolated FunctionRemote Function
DEPRECATED. Instead, use https://docs.readme.com/developers/reference/api-specification#deleteapispecification to delete a Swagger file in ReadMe
Parameters
- id string - ID of swagger the file
Deprecated
getVersions
Isolated FunctionRemote Function
Get versions
createVersion
Isolated FunctionRemote Function
Create version
Parameters
- payload Version - Version object
Return Type
getVersion
Isolated FunctionRemote Function
Get version
Parameters
- versionId string - Semver version indentifier
updateVersion
Isolated FunctionRemote Function
Update version
deleteVersion
Isolated FunctionRemote Function
Delete version
Parameters
- versionId string - Semver version indentifier
Records
readme: Changelog
Fields
- body string - Body content of the changelog
- title string - Title of the changelog
- 'type string(default "") -
readme: ClientHttp1Settings
Closed record
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy? ProxyConfig - Proxy server related options
readme: ConnectionConfig
Closed record
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth CredentialsConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings? ClientHttp1Settings - Configurations related to HTTP/1.x protocol
- http2Settings? ClientHttp2Settings - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache? CacheConfig - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- responseLimits? ResponseLimitConfigs - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
readme: CustomPage
Fields
- body? string - Body formatted in Markdown (displayed by default).
- html? string - Body formatted in HTML (sanitized, only displayed if
htmlmodeis true).
- htmlmode boolean(default false) - true if
htmlshould be displayed, false ifbodyshould be displayed.
- title string - Title of the custom page
readme: Doc
Fields
- body? string - Body content of the page, formatted in ReadMe or Github flavored Markdown. Accepts long page content, for example, greater than 100k characters
- category string - Category ID of the page, which you can get through https://docs.readme.com/developers/reference/categories#getcategory
- parentDoc? string - For a subpage, specify the parent doc ID, which you can get through https://docs.readme.com/developers/reference/docs#getdoc
- title string - Title of the page
- 'type? string - Type of the page. The available types all show up under the /docs/ URL path of your docs project (also known as the "guides" section). Can be "basic" (most common), "error" (page desribing an API error), or "link" (page that redirects to an external link)
readme: File
Fields
- spec? string - OpenAPI/Swagger file
readme: ProxyConfig
Closed record
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password
readme: Version
Fields
- codename? string - Dubbed name of version
- 'from string - Semantic Version to use as the base fork
- is_beta boolean(default true) -
- is_deprecated? boolean - Should this be deprecated? Only allowed in PUT operations
- is_stable? boolean - Should this be the main version
- 'version string - Semantic Version