Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ewenquim/swaglint
Linter for swaggo/swag
https://github.com/ewenquim/swaglint
go golang linter openapi swagger
Last synced: about 1 month ago
JSON representation
Linter for swaggo/swag
- Host: GitHub
- URL: https://github.com/ewenquim/swaglint
- Owner: EwenQuim
- License: agpl-3.0
- Created: 2022-07-28T09:13:43.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-03-19T13:39:38.000Z (almost 2 years ago)
- Last Synced: 2024-11-24T19:54:26.560Z (about 2 months ago)
- Topics: go, golang, linter, openapi, swagger
- Language: Go
- Homepage:
- Size: 38.1 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Swaglint - a linter for swaggo/swag
> And your documentation will always be up-to-date.
[](https://goreportcard.com/report/github.com/EwenQuim/swaglint)
As there are no code-generated swagger documentation in Go, only comments-based ones, this linter comes in handy and tries to force you to write better documentation. Using this tool, your code will always match your documentation. It can also be used to fix this documentation automatically.
## Examples
### ✅ GOOD:
```go
// PerfectlyDocumented
// @Summary Hello, world!
// @Tags user
// @Param name path string true "Name"
// @Router /hello/{name} [get]
func helloWorld(w http.ResponseWriter, r *http.Request) {
name := chi.URLParam(r, "name")
w.Write([]byte("Hello, " + name + "!"))
}
```
### ❌ REPORTED:
```go
func helloWorld(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello, world!"))
}
// REPORTED: swaglint: should have a swagger documentation
```
```go
// WronglyDocumented
// @Param notName path string true "Name"
// @Router /hello/{name} [get]
func helloWorld(w http.ResponseWriter, r *http.Request) {
name := chi.URLParam(r, "name")
w.Write([]byte("Hello, " + name + "!"))
}
// REPORTED: swaglint: should have the following tags: @Summary, @Tags
// REPORTED: swaglint: param should be named "name" and not "notName"
```
## Installation
```bash
go install github.com/EwenQuim/swaglint@latest
```
## Usage
```bash
swaglint ./...
swaglint package-name
swaglint -h
```
## Roadmap
The linter is **working**.
This roadmap is here to help me (and you, if you contribute!) to improve the linter. Even if it is incomplete, you can use it in your projects.
- [x] Detect not documented http handlers
- [x] Detect missing tags
- [x] Missing @Summary
- [x] Missing @Tags
- [x] Missing @Router
- [x] Mismatch in query param
- [x] For net/http
- [x] Mismatch in path param
- [x] For chi
- [ ] For gorilla/mux
- [ ] For fiber
- [ ] For gin
- [ ] Mismatch in response body
- [ ] ⏳ Full support for swaggo/swag (parse the comments section with swaggo's internal parser)
- [ ] Support for go-swagger/go-swagger
- [ ] Automatically generate the documentation with `-fix`