Générer une Documentation Swagger en Go : Comparaison Entre swag et go-swagger (2023)

Introduction

Lorsqu'il s'agit de documenter une API en Go, le choix entre deux bibliothèques Swagger, swag et go-swagger, peut être déterminant. Dans cet article, nous allons examiner les caractéristiques de chaque bibliothèque et déterminer laquelle est la mieux adaptée à vos besoins spécifiques.

Présentation des Bibliothèques

swag : Simplicité et Commodité

Swag se concentre sur la génération de documentation Swagger à partir du code source Go annoté. Sa simplicité d'utilisation en fait un choix attrayant pour ceux qui recherchent une solution directe. Cependant, examinons de plus près ce qu'il offre.

Structuration de la Documentation

Pour documenter une structure avec swag, il suffit d'ajouter des tags aux champs, comme illustré ci-dessous :

type ThingResponse struct {
    // The UUID of a thing
    UUID string `json:"uuid"`

    // The Name of a thing
    Name string `json:"name"`

    // The Value of a thing
    Value string `json:"value"`

    // The last time a thing was updated
    Updated time.Time `json:"updated"`

    // The time a thing was created
    Created time.Time `json:"created"`
}

Documentation des Endpoints

La documentation des endpoints nécessite également l'ajout de tags, comme illustré ici pour l'endpoint GetThing :

go-swagger : Puissance et Polyvalence

D'un autre côté, go-swagger offre plus que la simple génération de documentation Swagger. En plus de cela, il propose la possibilité de générer à la fois un client et un serveur à partir de la documentation Swagger. Voyons comment cela se traduit dans la pratique.

Documentation Structurée

Avec go-swagger, la documentation d'une structure ressemble à ceci :

// swagger:model ThingResponse
type ThingResponse struct {
    // The UUID of a thing
    // example: 6204037c-30e6-408b-8aaa-dd8219860b4b
    UUID string `json:"uuid"`

    // The Name of a thing
    // example: Some name
    Name string `json:"name"`

    // The Value of a thing
    // example: Some value
    Value string `json:"value"`

    // The last time a thing was updated
    // example: 2021-05-25T00:53:16.535668Z
    Updated time.Time `json:"updated"`

    // The time a thing was created
    // example: 2021-05-25T00:53:16.535668Z
    Created time.Time `json:"created"`
}

Documentation des Endpoints

L'annotation des fonctions et des structures est nécessaire pour documenter avec go-swagger. Par exemple, pour l'endpoint GetThing :

// swagger:route GET /thing/{uuid} Thing get-thing
//
// This is the summary for getting a thing by its UUID
//
// This is the description for getting a thing by its UUID. Which can be longer.
//
// responses:
//   200: ThingResponse
//   404: ErrorResponse
//   500: ErrorResponse
func (s *Server) GetThing(w http.ResponseWriter, r *http.Request) {
    // Your implementation here
}

Comparaison des Performances

Une différence notable entre les deux bibliothèques réside dans leurs performances. Sur notre exemple de cinq endpoints, swag génère la documentation en moins d'une demi-seconde, tandis que go-swagger prend 6 secondes. Pour des applications plus importantes, go-swagger peut montrer des signes de ralentissement.

Conclusion

En conclusion, le choix entre swag et go-swagger dépend de vos besoins spécifiques. Si la simplicité et la commodité sont vos priorités, swag pourrait être la meilleure option. Cependant, si vous recherchez une solution puissante avec la possibilité de générer un client et un serveur, go-swagger offre une polyvalence supplémentaire.

Lors de l'évaluation de ces bibliothèques, gardez à l'esprit vos préférences en termes de syntaxe de documentation et de performances. Les deux ont leurs avantages, mais en fin de compte, la meilleure solution dépend de la nature de votre projet et de vos exigences spécifiques.

Pour un exemple de mise en œuvre pratique de ces deux bibliothèques, vous pouvez consulter le code source fonctionnel sur .

En savoir plus sur la génération de documentation Swagger en Go sur .