UtiliserSwagger2ConstruireAPIDocumentation

Pourquoi publierAPIDocumentation de l'interface

Aujourd'hui, de nombreuses entreprises adoptent un modèle de développement séparé de l'avant et de l'arrière, Les travaux à l'avant et à l'arrière sont effectués par différents ingénieurs . Dans ce modèle de développement , Tenir à jour et complet API La documentation améliorera considérablement notre productivité . Traditionnellement, les documents sont utilisés par les développeurs d'arrière - plan wordÉcrit par, Je crois que tout le monde sait aussi qu'il est difficile d'assurer l'actualité des documents de cette façon , Au fil du temps, ce type de document perdra sa valeur de référence , Au lieu de cela, cela augmentera nos coûts de communication. .Et Swagger Nous a donné un nouvel entretien API La façon dont les documents sont, Voyons ce qu'il y a de mieux.

• Changement de code , Changement de document .Quelques notes sont nécessaires,Swagger Il peut être généré automatiquement à partir du Code API Documentation,Bonne garantie d'actualité des documents.
• Translinguisme,Soutien 40 Plusieurs langues.
• Swagger UI Ce qui est présenté est un API Documentation,Nous pouvons essayer directement sur la page du document APIAppel de,Le processus de préparation des paramètres d'appel complexes a été omis.
• Vous pouvez également importer les spécifications du document dans les outils connexes（Par exemple SoapUI）, Ces outils nous permettront de créer automatiquement des tests automatisés.

Intégrationswagger2Générer un document

D'abord parmavenIntroduction des coordonnéesswaggerBibliothèques de classe connexes.

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>

Et à traversjava ConfigC'est exact.Swagger2Configurer.

@Configuration
@EnableSwagger2
public class Swagger2 {

private ApiInfo apiInfo() {

return new ApiInfoBuilder()
.title("springbootUtilisationswaggerConstruireapiDocumentation")
.description(" Simple et élégant restfunStyle")
.termsOfServiceUrl("https://blog.csdn.net/m0_53157173")
.version("1.0")
.build();
}
@Bean
public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//ScanbasePackageSous le sac“/rest/” Le contenu sous le chemin est la cible de la construction du document d'interface 
.apis(RequestHandlerSelectors.basePackage("com.controller"))
.paths(PathSelectors.regex("/rest/.*"))
.build();
}
}

• @EnableSwagger2 L'annotation indique l'ouvertureSwaggerAPI Fonctions liées aux documents
• InapiInfo Pour configurer un document d'interface dans la méthode title(Titre)、Description、termsOfServiceUrl（Accords de services）、 Version et autres informations pertinentes
• IncreateRestApiDans la méthode,basePackage Indique quel packageEn bas.ControllerClasse commeAPI Portée du contenu du document d'interface
• IncreateRestApiDans la méthode,paths .Indique la méthode de cartographie du Contrôleur sous quel chemin de requête ,En tant queAPI Portée du contenu du document d'interface

Une fois l'intégration terminée , Effectuer une vérification d'accès ：http://localhost/swagger-ui.html ,Comme suit：

swagger Fournit non seulement une présentation statique de la documentation d'interface , Fournit également la possibilité d'effectuer des essais de méthode d'interface . Remplissez les paramètres de l'interface dans la figure suivante ,Cliquez sur“try it out" L'envoi de la demande d'interface et l'affichage des résultats de la réponse peuvent être réalisés .

ÉcrireswaggerNotes

En généralController La classe et la méthode ont été écrites swaggerNotes, Pas besoin d'écrire javaNotes. Mais l'auteur n'a presque jamais écrit swaggerNotes, C'est - à - dire cette section （Trois、ÉcrireswaggerNotes） Je n'ai jamais utilisé ce que j'ai dit. . Parce qu'une équipe mature , Le personnel de première ligne peut connaître le rôle de la méthode en fonction du nom de la méthode anglaise et du nom du paramètre , Si le développeur de code prend soin de nommer l'interface et les paramètres en anglais . Promotion au sein de l'équipe RESTful Principes de conception de l'interface et bonnes spécifications uniformes d'interaction , Pour savoir ce que signifie le résultat de la réponse .C'est aussi une sorte de“Convention supérieure à la configuration”L'incarnation de.

Bien sûr., Si votre équipe ne le fait pas “Accord“,Alors il faut“Configuration” Pour documenter . J'appelle ce processus “ Ajouter un commentaire à la fonctionnalité de l'interface ”.C'est écrit comme suit：

@ApiOperation(value = "Ajouter un article", notes = " Ajouter un nouvel article ", tags = "Article",httpMethod = "POST")
@ApiImplicitParams({

@ApiImplicitParam(name = "title", value = "Titre de l'article", required = true, dataType = "String"),
@ApiImplicitParam(name = "content", value = "Contenu de l'article", required = true, dataType = "String"),
@ApiImplicitParam(name = "author", value = "Auteur de l'article", required = true, dataType = "String")
})
@ApiResponses({

@ApiResponse(code=200,message="Succès",response=AjaxResponse.class),
})
@PostMapping("/article")
public @ResponseBody AjaxResponse saveArticle(
@RequestParam(value="title") String title, //Paramètres1
@RequestParam(value="content") String content,//Paramètres2
@RequestParam(value="author") String author,//Paramètres3
) {

swagger Une fois le commentaire ajouté , Le document d'interface ressemble à ceci （ Contient des instructions en chinois ）：

ApiModelUtilisation des annotations

@ApiModel(value = " Classe générale de structure des données de réponse ")
public class AjaxResponse {

@ApiModelProperty(value="La demande a - t - elle été traitée avec succès?")
private boolean isok; //La demande a - t - elle été traitée avec succès?
@ApiModelProperty(value="Code d'état de la réponse à la demande",example="200、400、500")
private int code; //Code d'état de la réponse à la demande（200、400、500）
@ApiModelProperty(value="Description des résultats de la demande")
private String message; //Description des résultats de la demande
@ApiModelProperty(value="Demande de données sur les résultats")
private Object data; //Demande de données sur les résultats（Généralement utilisé pour les opérations de requête）
}

La page affiche les résultats

Bien que l'auteur lui - même n'ait jamais écrit swaggerNotes, Mais il n'est pas exclu que certaines équipes pensent qu'elles peuvent l'utiliser. , Je vais donc vous donner plus de détails. :

@Api：Utilisé dansController Dans la classe Controller
Propriétéstags=" Décrire les fonctions et les fonctions de ce type "
@ApiOperation：Utilisé dansController Sur la méthode demandée par la classe Controller
value="Description de l'utilisation de la méthode、Action"
notes="Notes sur la méthode"
@ApiImplicitParams：Utilisé dans la méthode demandée,Représente un ensemble de descriptions de paramètres
@ApiImplicitParam： Description des paramètres de la méthode de demande
name：Nom du paramètre
value：Description en caractères chinois du paramètre、Explication、Objet
required：Le paramètre doit - il passer à,Type booléen
paramType：Type de paramètre, Où les paramètres sont stockés ou soumis
· header --> HttpDeHeader Acquisition des paramètres transportés ：@RequestHeader
· query --> Obtenir les paramètres de la requête：@RequestParam （Comme dans l'exemple ci - dessus）
· path（PourrestfulInterface）--> Obtenir les paramètres de la requête：@PathVariable
· body（Peu fréquent）
· form（Peu fréquent）
dataType：Type de paramètre,Par défautString,Autres valeursdataType="Integer"
defaultValue：Valeur par défaut du paramètre
@ApiResponses： Utilisé dans la méthode de demande du Contrôleur , Décrire les résultats de la réponse de la méthode
@ApiResponse： Utilisé pour exprimer un message de réponse
code：Nombre,Par exemple400
message：Information,Par exemple"Le paramètre de demande n'est pas rempli"
response： Classe d'encapsulation des résultats de la réponse , Dans l'exemple ci - dessus AjaxResponse.class
@ApiModel：value=“ Habituellement utilisé pour décrire @RequestBodyEt@ResponseBody Annotation Modified receive parameter or Response Parameter entity class ”
@ApiModelProperty：value=" Description des propriétés de la classe d'entité "

Comment désactiver dans un environnement de productionswagger2

Nos documents sont généralement visualisés et utilisés au sein de l'équipe , Vous ne voulez pas publier dans un environnement de production pour que les utilisateurs puissent voir .

• Désactiver la méthode1：Utiliser des notes@Profile({“dev”,“test”}) Indique qu'il est ouvert dans un environnement de développement ou d'essai , Et à l'arrêt de la production .
• Désactiver la méthode2：Utiliser des notes@ConditionalOnProperty(name = “swagger.enable”,havingValue = “true”) Puis dans la configuration de test ou de développement Ajouter swagger.enable = trueC'est prêt., Fermer par défaut si l'environnement de production n'est pas rempli Swagger.

UtiliserSwagger2MarkupRéaliser l'exportationAPIDocumentation

Swagger2Markup- Oui.GithubUn projet Open source sur. Le projet vise principalement à: Swagger Les documents générés automatiquement sont convertis en plusieurs formats populaires pour le déploiement et l'utilisation statiques ,Par exemple,：AsciiDoc、Markdown、Confluence.

GénérerAsciiDoc

GénérerAsciiDocIl y a deux façons：

AdoptionJavaCode pour générer

Première étape：Éditionpom.xml Augmentation des dépendances et des entrepôts connexes à utiliser

<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</dependency>
<repositories>
<repository>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>

Deuxième étape： Écrivez un cas d'essai d'Unit é pour générer le Code qui exécute le document généré

/** * GénérerAsciiDocsFormat du document * @throws Exception */
@Test
public void generateAsciiDocs() throws Exception {

// ProduitsAsciiFormat
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://127.0.0.1:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/asciidoc/generated"));
}
/** * GénérerMarkdownFormat du document * @throws Exception */
@Test
public void generateMarkdownDocs() throws Exception {

// ProduitsMarkdownFormat
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/markdown/generated"));
}
/** * GénérerConfluenceFormat du document * @throws Exception */
@Test
public void generateConfluenceDocs() throws Exception {

// ProduitsConfluenceFormat utilisé
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/confluence/generated"));
}
/** * GénérerAsciiDocsFormat du document, Et les assembler en un seul fichier * @throws Exception */
@Test
public void generateAsciiDocsToFile() throws Exception {

// ProduitsAscii Pour un seul fichier 
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/asciidoc/generated/all"));
}
/** * GénérerMarkdownFormat du document, Et les assembler en un seul fichier * @throws Exception */
@Test
public void generateMarkdownDocsToFile() throws Exception {

// ProduitsMarkdown Pour un seul fichier 
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/markdown/generated/all"));
}

Le code ci - dessus est simple , Description générale de plusieurs éléments clés ：

• MarkupLanguage.ASCIIDOC： Spécifie le format final à exporter .Sauf queASCIIDOCAu - delà,EtMARKDOWNEtCONFLUENCE_MARKUP
• from(new URL("http://localhost:8080/v2/api-docs")： Configuration de la source spécifiée pour générer un document de déploiement statique , Ça pourrait être comme ça. URLForme, Peut également correspondre SwaggerStandardString Type ou flux lu à partir d'un fichier . Si elle est actuellement utilisée SwaggerProjets, Nous accédons localement en utilisant SwaggerMode d'interface, Si obtenu de l'extérieur Swagger Profil du document , Vous pouvez utiliser une chaîne ou lire un fichier
• toFolder(Paths.get("src/docs/asciidoc/generated")： Spécifiez l'emplacement du Répertoire pour le fichier final généré

Si vous ne voulez pas diviser le fichier de résultats , Peut également être remplacé toFolder(Paths.get("src/docs/asciidoc/generated")PourtoFile(Paths.get("src/docs/asciidoc/generated/all")), Exporter les résultats de la transformation dans un seul fichier , Ceci peut éventuellement générer html C'est aussi unique .

Après avoir exécuté le cas d'essai ci - dessus , Nous pouvons obtenir ce qui suit dans le catalogue du projet actuel ：

Je vois., Cette méthode est générée après l'exécution 5 Différents fichiers statiques .

AdoptionMavenPlug - in pour générer

En plus d'écrire Java En dehors de la façon dont le Code est généré ,swagger2markupLesMavenPlug - in pour utiliser. Pour la construction ci - dessus , Peut être réalisé en pom.xml Ajouter les plug - ins suivants pour compléter la génération de contenu statique .

<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
<outputDirectory>./docs/asciidoc/html</outputDirectory>
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!-- La barre de menu est à gauche -->
<toc>left</toc>
<!-- Disposition Multi - titres -->
<toclevels>3</toclevels>
<!-- Numérotation automatique -->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>

Configurer les commandes d'exécution

Avec la configuration ci - dessus, Exécuter le plug - in asciidoctor:process-asciidocAprès la commande,- Oui.docs/asciidoc/html Générer le déploiement statique final disponible sous le Répertoire HTMLC'est. Une fois la construction terminée , Peut être visualisé directement dans le Navigateur , Vous pouvez voir les résultats du déploiement statique comme dans l'image ci - dessous ：

Articles de référence

UtiliserSwagger2MarkupRéaliser l'exportationAPIDocumentation

SwaggerTransfert de documentsWord Documentation

github

spring boot2.0+swaggerGénération automatiquePDFEtHTMLFormatAPIDocumentation

swagger+asciidoctor ExporterPDF Résoudre le problème du Code chinois manquant

Swagger3-C'est - à - dire:OpenAPIFaire

OpenAPI Est le nom officiel de la spécification . Travaux d'élaboration de spécifications 2015Début de l'année,À ce moment - là,SmartBear（ResponsableSwagger Entreprises de développement d'outils ）Oui.Swagger 2.0 Le cahier des charges a été donné à Open API Initiative, L'Association est composée de 30 Composition de plusieurs organisations .Par la suite, La spécification a été renommée OpenAPISpécifications.

Swagger

• C'est un API Organisation de la maintenance des documents ,C'est devenu Open API Définition principale de la norme . La dernière version est maintenant 17Publié en Swagger3（Open Api3）.
• C'est unOpen API Kit de mise en œuvre des spécifications ,Parce queSwagger L'outil est créé par la participation Swagger Développé par une équipe normalisée , Par conséquent, ces outils sont généralement considérés comme des pronoms pour cette spécification . Pour l'instant, on peut considérer que Swagger3C'estOpen API 3.0

OpenAPI 3.0：2017Année7Mois,Open API InitiativeEnfin publiéOpenAPI Specification 3.0.0.C'est vrai.2.0 De nombreuses améliorations ont été apportées aux spécifications. .Open API 3.0 Les spécifications peuvent être utilisées JSONOuYAMLCompilation, Et il enregistre RESTful APIBien joué..En même temps,Swagger2C'est du passé..

SpringFox- Oui. spring Un projet d'entretien communautaire （Non officiel）, Aider les utilisateurs à swagger2 Intégration dans Spring Moyenne.Souvent utilisé Spring Aide les développeurs à générer des documents , Et peut facilement spring bootUtilisé dans.Jusqu'à2020Année4Mois,Pas encore pris en charge OpenAPI3 Critères.

SpringDocC'est aussi spring Un projet d'entretien communautaire （Non officiel）, Aider les utilisateurs à swagger3 Intégration dans Spring Moyenne.
C'est aussi pour Spring Aide les développeurs à générer des documents , Et peut facilement spring bootUtilisé dans

Intégrationspringdoc-openapi

Inpom.xml Retirer à l'intérieur springfox,Ajouter ce qui suit:openapiDépendance.

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.4.0</version>
</dependency>

C'est si simple., Le document est terminé. , Aucune autre configuration n'est nécessaire .

Accès à：http://localhost:8888/swagger-ui.html

Oui.APIPrésentation groupée

Méthode de configuration

@Configuration
public class OpenAPIConfig {

@Bean
public GroupedOpenApi restApi() {

return GroupedOpenApi.builder()
.group("rest-api")
.pathsToMatch("/rest/**")
.build();
}
@Bean
public GroupedOpenApi helloApi() {

return GroupedOpenApi.builder()
.group("hello")
.pathsToMatch("/hello/**")
.build();
}
}

Afficher les effets, Sélectionner les groupes par la liste déroulante , Voir dans le Groupe API

Utiliser swagger3 Note au lieu de swagger2Notes

Si vous souhaitez ajouter des commentaires plus détaillés en chinois à votre document , Utilisez l'annotation suivante （ComparerSwagger2 Comment utiliser les annotations ）. Mais je ne pense pas qu'il soit nécessaire d'apprendre ça. ,Ça ne veut rien dire.Notez les variables、Spécification de désignation de l'interface, Les documents d'interface en anglais sont très bons .

Avec swagger 3 Notes（ Déjà là - haut mavenIntroduction du paquet）Remplacer swagger 2 Notes,swagger 3 Le chemin du paquet pour l'annotation est io.swagger.v3.oas.annotations.

swagger3.0 Référence de la version tierce partie :

swagger3