managua1902
I have REST API project for which I need to generate documentation.
I’ve looked into phoenix_swagger | Hex . However, as I’ve found out, it requires adding Elixir code right next to each API function:
swagger_path :index do
get "/api/users"
summary "List users"
description "List all users in the database"
tag "Users"
produces "application/json"
response(200, "OK", Schema.ref(:UsersResponse),
example: %{
data: [
%{
id: 1,
count: 42,
email: "some email",
name: "some name",
private: true,
profile: "some profile",
}
]
}
)
end
def index(conn, _params) do
users = Users.list_users()
render(conn, "index.json", users: users)
end
This will greatly litter the code where it’ll be unnecessary, in my opinion.
Is there other Elixir Swagger library which is up to date and usable? Or how else will I generate the REST API docs?
Where Next?
Trending in Questions
Other Trending Topics
Latest Phoenix Threads
Latest on Elixir Forum
Sponsor Spotlight
Build Elixir applications with speed and confidence.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #library
- #deployment
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #elixirconf
- #channels
- #exunit
- #discussion
- #code-sync
- #podcasts
- #javascript
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixirconf-us
- #ai
- #blog-post
- #elixir-ls
- #phoenix_html
- #iex
- #graphql
- #genstage
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #metaprogramming
- #hex
- #security
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Error tracking, logs, uptime, and Just Enough APM. Built for developers.
Elixir, Erlang & BEAM conferences from Code Sync - join us in 2026!
Bringing learning, work and compliance together since 1987.
Producing high quality Elixir screencasts since 2017.
**Building the future of software with AI, trust, and human connection.**
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
Showing Posts 15 to 6- Show Best Posts
- Show All (oldest first)
- Show All (newest first)
smathy
Well in
rswagthe API version is just one of the swagger annotations you put in your tests, it defaults to the first version (that you’ve defined in your swagger config) but when you have multiple versions then you just annotate your v1 tests to be for your v1 docs, v2 for v2, etc.ityonemo
How do you maintain multiple versions of the schema if they’re generated from the tests?
ityonemo
If you want to go from schema to router there’s apical.
managua1902
What are the downsides of the approach you’ve suggested then?
tfwright
It’s exactly what you’re asking for:
managua1902
Re-read 2-3 the previous responses
dimitarvp
Ability to generate dynamic web documentation of your API. Some tools even allow baking requests to the API from the web page where the documentation is.
managua1902
What are the upsides of this?
tfwright
Why not just maintain your own json spec then? A good chunk of the functionality of these libraries is consolidating your Elixir function docs into a single OpenApi document. If you won’t want your spec in Elixir just build it in json or yaml or whatever?
managua1902
But it uses the same approach: a lot of code-description next to each end point, right in the Elixir code.
There’s no way to go around this, right? What I want is to keep the description of each REST API endpoint somewhere aside, in a separate file or files.