added swagger docs (#30)

edipermadi · Nov 5, 2023 · cb28bb0 · cb28bb0
1 parent 9eff2fe
commit cb28bb0
Show file tree

Hide file tree

Showing 6 changed files with 2,370 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -1,16 +1,20 @@
 # music-db
 
-Music Database is an attempt to make an encyclopedic database of scales based on [William Zeitler](https://allthescales.org) classification.
+Music Database is an attempt to make an encyclopedic database of scales based
+on [William Zeitler](https://allthescales.org) classification.
 
 This project consists of:
+
 - postgres database seed generator
 - music theory data API
 
 The project is bundled as a docker cluster containing
+
 - postgres 16 database prefilled with music data
 - HTTP REST API server
 
 Features:
+
 - 12 semitones per octave
 - Supports 1490 scales
 - Supports 17880 keys
@@ -31,6 +35,7 @@ Features:
 ```shell
 make test
 ```
+
 ## Building
 
 To get database up and running
@@ -40,11 +45,12 @@ docker-compose up
 ```
 
 ## Example Queries
+
 ### Listing Pitches of a key
 
 ```postgresql
 SELECT k.name AS key,
-       p.name    AS pitch,
+       p.name AS pitch,
        kp.pitch_id
 FROM key_pitches kp
          JOIN keys k ON kp.key_id = k.id
@@ -69,6 +75,7 @@ WHERE k.name = 'CNaturalIonian';
 ## Query by API
 
 ### Listing Pitches
+
 ```shell
 $ curl localhost:3000/api/v1/theory/pitches
 [{"id":1,"name":"CNatural"},{"id":2,"name":"CSharp"},{"id":3,"name":"DNatural"},{"id":4,"name":"DSharp"},{"id":5,"name":"ENatural"},{"id":6,"name":"FNatural"},{"id":7,"name":"FSharp"},{"id":8,"name":"GNatural"},{"id":9,"name":"GSharp"},{"id":10,"name":"ANatural"},{"id":11,"name":"ASharp"},{"id":12,"name":"BNatural"}]
@@ -113,10 +120,10 @@ Pagination via query string `page` and `per_page`
 
 ### Keys
 
-| Method | Path                                  | Description            |
-|--------|---------------------------------------|------------------------|
-| GET    | `/api/v1/theory/keys/{:id}/chords`    | List key chords        |
-| GET    | `/api/v1/theory/keys/{:id}/modes`     | List key modes         |
-| GET    | `/api/v1/theory/keys/{:id}/pitches`   | List key pitches       |
-| GET    | `/api/v1/theory/keys/{:id}`           | Get key detail         |
-| GET    | `/api/v1/theory/keys`                 | List keys              |
+| Method | Path                                | Description      |
+|--------|-------------------------------------|------------------|
+| GET    | `/api/v1/theory/keys/{:id}/chords`  | List key chords  |
+| GET    | `/api/v1/theory/keys/{:id}/modes`   | List key modes   |
+| GET    | `/api/v1/theory/keys/{:id}/pitches` | List key pitches |
+| GET    | `/api/v1/theory/keys/{:id}`         | Get key detail   |
+| GET    | `/api/v1/theory/keys`               | List keys        |
diff --git a/api/Dockerfile b/api/Dockerfile
@@ -3,20 +3,28 @@ FROM golang:1.21 AS builder
 WORKDIR /build
 RUN adduser -u 10001 -disabled-password -gecos '' music-api
 
+RUN wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.9.1.tar.gz -O swagger-ui-5.9.1.tar.gz
+RUN mkdir -p dist
+RUN tar -C dist --strip-components=2 -xzvf swagger-ui-5.9.1.tar.gz swagger-ui-5.9.1/dist
+RUN sed -i 's|https://petstore.swagger.io/v2/swagger.json|./swagger.json|g' dist/swagger-initializer.js
+
 COPY go.mod .
 COPY go.sum .
 RUN go mod download
 
 COPY . .
 RUN CGO_ENABLED=0 GOARCH=amd64 GOOS=linux go build -a -o music-api cmd/api/main.go
 
+
 FROM alpine:3.18 AS final
 
 WORKDIR /app
 COPY --from=builder /etc/passwd /etc/passwd
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /build/music-api /app/music-api
+COPY --from=builder /build/dist /app/docs/dist
 COPY config /app/config
+COPY docs/swagger.json /app/docs/dist
 
 EXPOSE 3000
 

diff --git a/cmd/api/main.go b/cmd/api/main.go
@@ -31,9 +31,12 @@ func main() {
 	}
 
 	router := mux.NewRouter()
-	apiRouter := router.PathPrefix("/api/").Subrouter()
+	apiRouter := router.PathPrefix("/api").Subrouter()
+
 	apiV1Router := apiRouter.PathPrefix("/v1").Subrouter()
-	theoryV2Router := apiV1Router.PathPrefix("/theory").Subrouter()
+	theoryRouter := apiV1Router.PathPrefix("/theory").Subrouter()
+
+	apiRouter.PathPrefix("/docs").Handler(http.StripPrefix("/api/docs/", http.FileServer(http.Dir("./docs/dist/"))))
 
 	user := vpr.GetString("db.user")
 	password := vpr.GetString("db.password")
@@ -54,7 +57,7 @@ func main() {
 	theoryRepository := theory.NewRepository(logger, db)
 	theoryService := theory.NewService(logger, theoryRepository)
 	handlerHandler := theory.NewHandler(logger, theoryService)
-	handlerHandler.InstallEndpoints(theoryV2Router)
+	handlerHandler.InstallEndpoints(theoryRouter)
 
 	srv := &http.Server{
 		Handler:           handlers.RecoveryHandler(handlers.PrintRecoveryStack(true))(router),