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.
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();
}
}
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 .
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é "
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 .
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érerAsciiDocIl y a deux façons:
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_MARKUPfrom(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 .
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 :
UtiliserSwagger2MarkupRéaliser l'exportationAPIDocumentation
SwaggerTransfert de documentsWord Documentation
spring boot2.0+swaggerGénération automatiquePDFEtHTMLFormatAPIDocumentation
swagger+asciidoctor ExporterPDF Résoudre le problème du Code chinois manquant
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
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
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
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
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 :