HarelM left a comment (openstreetmap/openstreetmap-website#3107)
+1 for swagger/openAPI generated docs instead of a wiki maintenance, see my
comment here: https://github.com/openstreetmap/openstreetmap-website/pull/5943.
In general, now that OSM backend supports Oauth2 token, one can set this token
in a swagger UI to send authenticated requests through this UI, which is also
great for testing and a great developer experience.
I have an example of my site. which is written in C# and has the swagger UI
generated from the code, as can be seen here:
https://israelhiking.osm.org.il/swagger/index.html
Since my site uses OSM as third party authentication you can use your OSM token
there to get user data (If you are interested in trying it out).
I have very little experience with ruby, so I wouldn't know where to start in
order to integrate it, but in general, you can start by only integrating it and
not exposing it until you are happy with what it offers.
In C# you only add annotations to the functions of the controller, and some
comments, and swashbuckle (probably the equivalent of rswag) generates the open
API spec and the swagger UI straight from the code, no need to maintain
anything beside code documentation, which lies next to the code itself, and is
really easy to maintain.
But I don't know if this is easy for ruby...
According to chatGPT this is process (which I believe is at least 50%
implemented already):
With **Rswag**, you document your API **by writing RSpec tests** that describe
each endpoint's behavior, inputs, and outputs.
It's a clever setup because it:
✅ **Documents** your API (OpenAPI-compliant YAML/JSON)
✅ **Tests** that your API behaves as expected
✅ **Feeds** that documentation directly into Swagger UI
---
### 📌 Why this approach?
Instead of writing Swagger YAML manually (which can get messy and out of sync),
you:
- Write a test for `GET /posts`
- Describe its parameters, responses, and schema
- Run the test, which generates the Swagger JSON
- View the result in Swagger UI
---
### 🧠Example: Document + test `GET /users`
Let's say you have a `UsersController` with an index action. You can create a
test like this:
```ruby
# spec/integration/users_spec.rb
require 'swagger_helper'
RSpec.describe 'Users API', type: :request do
path '/users' do
get 'Retrieves all users' do
tags 'Users'
produces 'application/json'
response '200', 'users found' do
schema type: :array, items: {
type: :object,
properties: {
id: { type: :integer },
name: { type: :string },
email: { type: :string }
},
required: [ 'id', 'name', 'email' ]
}
run_test!
end
end
end
end
```
That does **two things at once**:
- 🎯 Describes the endpoint to Swagger
- ✅ Validates that a 200 response is returned and matches the schema
---
So yeah—you're integrating Swagger by writing **RSpec tests that double as
documentation**. It's a two-for-one deal: test coverage + interactive docs.
Want help writing one for a real route in your app? Just tell me which
controller/action you'd like to document.
--
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/3107#issuecomment-2828915771
You are receiving this because you are subscribed to this thread.
Message ID:
<openstreetmap/openstreetmap-website/issues/3107/2828915...@github.com>_______________________________________________
rails-dev mailing list
rails-dev@openstreetmap.org
https://lists.openstreetmap.org/listinfo/rails-dev
