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
Practical resources that improve the lives of professional developers.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #blog-post
- #phoenix_html
- #iex
- #ai
- #graphql
- #genstage
- #elixirconf-us
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #metaprogramming
- #security
- #hex
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Error tracking, logs, uptime, and Just Enough APM. Built for developers.
Develop your skills with books, videos, and courses.
Bringing learning, work and compliance together since 1987.
The deployment platform built for Elixir: PaaS ease, VPS control.
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
Showing Posts 1 to 10- Show Best Posts
- Show All (oldest first)
- Show All (newest first)
D4no0
There is GitHub - open-api-spex/open_api_spex: Open API Specifications for Elixir Plug applications · GitHub, the up-to-date library for generation of openapi docs, it does more things automatically, however you will still need to describe the operation.
tfwright
I think most people consider it a big advantage to have the docs next to the function, since they change together. I agree the phoenix_swagger DSL feels a bit “intrusive,” I prefer to use module attributes and build the open_api JSON from those.
I built docout to make it easier to use custom notation to convert function docs into documentation files (like an open_api.json) during the compilation phase.
smathy
I really like the
rswagapproach of integrating with the test interface, seems like the most natural place to have the docs and I’m surprised none of the Elixir projects have taken that direction.tfwright
I used rswag in my last major Rails project and while it’s nice having the little extra guarantee than your docs are accurate, I still prefer having docs next to the endpoint that I’m documenting, especially since Elixir supports such highly structured docs. And if you really want to guarantee accuracy you need to add a lot of extra assertions and if that kind of guarantee is not really necessary there’s not nearly as much advantage to coupling your doc generation to tests.
I also found rswag a little rough around the edges when it came to actually using it, since it needs to have a 1-1 DSL parity for every open_api feature, so it doesn’t take long into you run into things are not supported, or just really awkward to use. Of course back then it seemed like the open_api spec was more in flux than it is now.
smathy
I’m sure this is true, when I’ve used it it’s been either for an externally-facing API, or where we’ve had separate mobile and backend teams who only ever interacted by API contract, both situations where accuracy was a very high priority.
Edit: honestly, I don’t think I’d bother with swagger in a situation where that wasn’t the case, but obviously YMMV.
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.
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
What are the upsides of this?
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
Re-read 2-3 the previous responses