bullet_train-api 1.6.37 → 1.6.38

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5998b9f275e4d510c6813400d6901bbcdae7dd64d2050ab73ba0e7591be07940
-  data.tar.gz: 13fb31eb150e116cfcf05775950a24bd7cd416e39624d7acdc9cad41819f50b5
+  metadata.gz: 032efe953b88f9db79bee4f1e1b53f9a25b168a3579620d3c5e4ffe213734984
+  data.tar.gz: 3c15eabd737d77781282cef0be064121d35f1dffe4b012818fca5ac5c971ba85
 SHA512:
-  metadata.gz: 84762565f3bf2ed15536a7903911fc49d5caad26ac303331122d65dba0428dbb1f96a59a8994162f3debbdfd16c3b264e967fc6b651ffceac6ef9c621c775bfb
-  data.tar.gz: a3d559780886d26c9833e2a2219a78164c61a0b8e85ef54b35bc9a9d31c1c5a3296a36507c596c1ff47fab39f1269d1b2ac4dbdfa25e8a2a771980a1041f849b
+  metadata.gz: 40fb6d61b1968e0e584512bf33797432712665629bc16991b930a5a0934dde01c87512f213bc1db0b3145fee6e558abd1520814564ad1f682257dffe8eeda3b4
+  data.tar.gz: 1465a7fa12bd8be5d1ca2daaeb08c456acd7416b26dd880a8fac3ac31f63774227e675d4bc9066658e72c7d288fcc33a1940dbf2fdc64bee0ba4b3970306a6c3

data/README.md

@@ -1,28 +1,267 @@
 # BulletTrain::Api
-Short description and motivation.
+API capabilities for apps built with Bullet Train framework.
 
-## Usage
-How to use my plugin.
+## Quick Start
 
-## Installation
-Add this line to your application's Gemfile:
+### Installation
 
-```ruby
-gem "bullet_train-api"
-```
+Add this to your Gemfile:
 
-And then execute:
-```bash
-$ bundle
-```
+    gem "bullet_train-api"
 
-Or install it yourself as:
-```bash
-$ gem install bullet_train-api
-```
+Then, run `bundle` or install it manually using `gem install bullet_train-api`.
+
+## Contents
+
+- [API](#api)
+  - [Accessing](#accessing)
+  - [Versioning](#versioning)
+  - [Views](#views)
+- [Documentation](#documentation)
+  - [Index file](#index-file)
+  - [Automatic Components](#automatic-components)
+  - [Automatic Paths](#automatic-paths)
+  - [External Markdown files](#external-markdown-files)
+  - [Examples](#examples)
+  - [Example IDs](#example-ids)
+  - [Associations](#associations)
+  - [Localization](#localization)
+- [Rake Tasks](#rake-tasks)
+  - [Bump version](#bump-version)
+  - [Export OpenAPI document in file](#export-openapi-document-in-file)
+  - [Push OpenAPI document to Redocly](#push-openapi-document-to-redocly)
+  - [Create separate translations for API](#create-separate-translations-for-api)
+- [Contributing](#contributing)
+- [License](#license)
+- [Sponsor](#open-source-development-sponsored-by)
+
+### API
+
+BulletTrain::Api defines basic REST actions for every model generated with super-scaffolding.
+
+#### Accessing
+
+BulletTrain::Api uses Bearer token as a default authentication method with the help of [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) gem.
+It uses the idea that in order to access the API, there should be a Platform Application object, which can have access to different parts of the application.
+In Bullet Train, each Team may have several Platform Applications (created in Developers > API menu). When a Platform Application is created,
+it automatically generates an Bearer Token needed to access the API, controlled by this Platform Application.
+
+#### Versioning
+
+Versions are being set automatically based on the location of the controller.
+
+Current version can also be checked with
+````ruby
+BulletTrain::Api.current_version
+````
+
+#### Views
+All API response templates are located in `app/views/api/<version>/` and are written using standard jbuilder syntax.
+
+### Documentation
+
+This gem automatically generates OpenAPI 3.1 compatible documentation at:
+
+    /api/v1/openapi.yaml
+
+
+#### Index File
+
+    app/views/api/v1/open_api/index.yaml.erb
+
+The index file is the central point for the API documentation. This consists of a number of sections,
+some that get pulled in and bundled at build time.
+
+The file is in YAML format, but includes erb code which generates additional YAML with the help of [`jbuilder-schema`](https://github.com/bullet-train-co/jbuilder-schema) gem.
+
+#### Automatic Components
+
+There are several helper methods available in Index file.
+One of them is `automatic_components_for`, which generates two schemas of a model, Attributes and Parameters, based on it's Jbuilder show file.
+Parameters are used in requests and Attributes are used in responses.
+
+For example this code:
+````yaml
+components:
+  schemas:
+    <%= automatic_components_for User %>
+````
+looks for the file `app/views/api/v1/users/_user.json.jbuilder`.
+Let's say it has this contents:
+````ruby
+json.extract! user,
+  :id,
+  :email,
+  :name
+````
+then the produced component will be:
+````yaml
+components:
+  schemas:
+    UserAttributes:
+      type: object
+      title: Users
+      description: Users
+      required:
+      - id
+      - email
+      properties:
+        id:
+          type: integer
+          description: Team ID
+        email:
+          type: string
+          description: Email Address
+        name:
+          type:
+          - string
+          - 'null'
+          description: Name
+      example:
+        id: 42
+        email: generic-user-1@example.com
+        name: Example Name
+    UserParameters:
+      type: object
+      title: Users
+      description: Users
+      required:
+      - email
+      properties:
+        email:
+          type: string
+          description: Email Address
+        name:
+          type:
+          - string
+          - 'null'
+          description: Name
+      example:
+        email: generic-user-1@example.com
+        name: Example First Name
+````
+As you can see, it automatically sets required fields based on presence validators of the model,
+field types based on the value found in Jbuilder file, descriptions and examples.
+More on how it works and how you can customize the output in [`jbuilder-schema`](https://github.com/bullet-train-co/jbuilder-schema) documentation.
+
+#### Automatic Paths
+
+Method `automatic_paths_for` generates basic REST paths. It accepts model as it's argument.
+To generate paths for nested models, pass parent model as a second argument. It also accepts `except` as a third argument,
+where you can list actions which paths you don't want to be generated.
+
+If the methods defined in the `automatic_paths_for` for the endpoints support
+a write action (i.e. create or update), then doc generation uses the `strong_parameters`
+defined in the corresponding controller to generate the Parameters section in the schema.
+
+Automatic paths are generated for basic REST actions. You can customize those paths or add your own by creating a
+file at `app/views/api/<version>/open_api/<Model.underscore.plural>/_paths.yaml.erb`. For REST paths there's no need to 
+duplicate all the schema, you can specify only what differs from auto-generated code.
+
+#### External Markdown files
+
+External text files with Markdown markup can be added with `external_doc` method.
+It assumes that the file with `.md` extension can be found in `app/views/api/<version>/open_api/docs`.
+You can also use `description_for` method with a model, then there should be file `app/views/api/<version>/open_api/docs/<Model.name.underscore>_description.md`
+
+This allows including external markdown files in OpenAPI schema like in this example:
+
+````yaml
+openapi: 3.1.0
+info:
+  ...
+  description: <%= external_doc "info_description" %>
+  ...
+tags:
+  - name: Team
+    description: <%= description_for Team %>
+  - name: Addresses::Country
+    description: <%= description_for Addresses::Country %>
+  ...
+````
+supposing the following files exist:
+````
+app/views/api/v1/open_api/docs/info_description.md
+app/views/api/v1/open_api/docs/team_description.md
+app/views/api/v1/open_api/docs/addresses/country_description.md
+````
+
+#### Examples
+
+In order to generate example requests and responses for the documentation in the
+`automatic_components_for` calls, the bullet_train-api gem contains `ExampleBot`
+which uses FactoryBot to build an in-memory representation of the model,
+then generates the relevant OpenAPI schema for that model.
+
+ExampleBot will attempt to create an instance of the given model called `<model>_example`.
+For namespaced models, `<plural_namespaces>_<model>_example`
+
+For example, for the Order model, use `order_example` factory.
+
+For Orders::Invoices::LineItem, use `orders_invoices_line_item_example` factory.
+
+When writing the factory, the example factory should usually inherit from the existing factory,
+but in some cases (usually if the existing factory uses callbacks or creates associations
+that you may not want), you may wish to not inherit from the existing one.
+
+##### Example IDs
+
+Since we only want to use in-memory instances, we need to ensure that all examples
+have an `id` specified, along with `created_at` and `updated_at`, otherwise they
+will show as `null` in the examples.
+
+You may wish to use `sequence` for the id in the examples, but you need to be careful
+not to create circular references (see Associations section below)
+
+##### Associations
+
+You need to be careful when specifying associated examples since it is easy to get
+into a recursive loop (see Example IDs section above). Also, ensure that you only
+create associations using `FactoryBot.example()` and not `create`, otherwise it will
+create records in your database.
+
+#### Localization
+
+The documentation requires that `"#{model.name.underscore.pluralize}.label"` localisation value is defined,
+which will be used to set model title and description.
+
+### Rake Tasks
+
+#### Bump version
+
+Bump the current version of application's API:
+
+    rake bullet_train:api:bump_version
+
+#### Export OpenAPI document in file
+
+Export the OpenAPI schema for the application to `tmp/openapi` directory:
+
+    rake bullet_train:api:export_openapi_schema
+
+#### Push OpenAPI document to Redocly
+
+Needs `REDOCLY_ORGANIZATION_ID` and `REDOCLY_API_KEY` to be set:
+
+    rake bullet_train:api:push_to_redocly
+
+#### Create separate translations for API
+
+Starting in 1.6.28, Bullet Train Scaffolding generates separate translations for API documentation: `api_title` and `api_description`.
+This rake task will add those translations for the existing fields, based on their `heading` value:
+
+    rake bullet_train:api:create_translations
+
+It only needs to be run once after upgrade.
 
 ## Contributing
-Contribution directions go here.
+
+Contributions are welcome! Report bugs and submit pull requests on [GitHub](https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-api).
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+This gem is open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## Open-source development sponsored by:
+
+<a href="https://www.clickfunnels.com"><img src="https://images.clickfunnel.com/uploads/digital_asset/file/176632/clickfunnels-dark-logo.svg" width="575" /></a>

data/lib/bullet_train/api/version.rb

@@ -1,5 +1,5 @@
 module BulletTrain
   module Api
-    VERSION = "1.6.37"
+    VERSION = "1.6.38"
   end
 end

data/lib/tasks/bullet_train/api_tasks.rake

@@ -92,7 +92,7 @@ namespace :bullet_train do
       puts "Finished bumping to #{new_version}"
     end
 
-    desc "Bump the current version of application's API"
+    desc "Push OpenAPI yaml file to Redocly"
     task push_to_redocly: :environment do
       include Rails.application.routes.url_helpers
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train-api
 version: !ruby/object:Gem::Version
-  version: 1.6.37
+  version: 1.6.38
 platform: ruby
 authors:
 - Andrew Culver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-03-11 00:00:00.000000000 Z
+date: 2024-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -164,7 +164,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Bullet Train API
+description: API capabilities for apps built with Bullet Train framework
 email:
 - andrew.culver@gmail.com
 executables: []