Example

Example #

Given a sample Go project with HTTP routes running EndpointElf will generate an OpenAPI document like the following:

package main

import (
	"encoding/json"
	"net/http"
	"time"

	"github.com/gorilla/mux"
)

func main() {
	handler := mux.NewRouter()
	handler.
		Methods("POST").
		Path("/comments").
		HandlerFunc(handleNewComment)
}

func handleNewComment(w http.ResponseWriter, r *http.Request) {
	userID := r.Header.Get("X-User-ID")

	var req CreateComment
	json.NewDecoder(r.Body).Decode(&req)

	if err := req.Validate(); err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}

	comment, err := saveComment(userID, req)
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(comment)
}

type CreateComment struct {
	Text string
}

func (c CreateComment) Validate() error {
	return nil
}

func saveComment(userID string, req CreateComment) (*Comment, error) {
	return nil, nil
}

type Comment struct {
	Author    string
	Text      string
	CreatedAt time.Time
}
openapi: 3.0.0
info:
  contact: {}
  description: API for managing comments
  license:
    name: ""
  title: API
  version: 1.0.0
paths:
  /comments:
    post:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
          description: Successful operation
          headers:
            Content-Type:
              description: application/json
              schema:
                type: string
        "400":
          content:
            application/json:
              schema:
                type: string
          description: Bad request
        default:
          description: ""
components:
  schemas:
    Comment:
      properties:
        Author:
          type: string
        CreatedAt:
          format: date-time
          type: string
        Text:
          type: string
      type: object
    CreateComment:
      properties:
        Text:
          type: string
      type: object

EndpointElf runs on Go source code and inspects the code directly (traverses the AST) to extract HTTP routes. EndpointElf can also run AI agents over your code to improve descriptions and provide examples.

Try out EndpointElf today on your Go project!

Open Source Examples #

We have a repository of generated specifications from open-source HTTP servers.