[openstreetmap/openstreetmap-website] Documenting API using Swagger / rswag (#3107)

[Harel M]

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/2828915771 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20250424/cb6c7f0e/attachment.htm>