Les documents d'interface externe ont toujours été relativement primitifs et, essentiellement, des documents manuscrits sont passés. Récemment, j'ai découvert un nouveau jouet, ce qui peut économiser beaucoup de problèmes sur l'interface.
Swagger est un cadre de documentation API pratique. Il peut afficher le type d'interface à l'autre développeur de la manière la plus complète, en évitant le comportement unilatéral et l'erreur des documents manuscrits.
Il existe actuellement deux types de fanfaronniers et de fanfaronniers2. 1 est plus gênant, vous n'envisagez donc pas de l'utiliser. Cet article enregistre principalement deux façons d'utiliser Swagger2 comme interface externe. Veuillez le vérifier plus tard.
1. Utilisez le printemps traditionnel pour intégrer Swagger2
1. Dépendance Maven
<!--springfox dependencies--> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version> 2.6.3 </ version> </ Dependency> <Dedency> <ProupId> com.fasterxml.jackson.core </prôdId> <ArtifActid> Jackson-Annotations </ Artifactid> <DERVIÈRE> 2.6.3 </DERNIFRATION> <ArtefactId> Springfox-Swagger2 </letefactId> <Dersion> 2.4.0 </-version> </Dependency> <Dedency> <ProupID> io.springfox </romp grouped> <Artefactive> Springfox-sagger-Ui </lefacactid> <in version> 2.4.0 </DERNIFRICATION>
2. Ajoutez une configuration de mappage statique dans Spring-Mvc.xml (en fait, je peux supprimer cela dans mon projet, je ne sais pas quelle est la situation):
<! - Path de fichier statique de Swagger -> <mvc: ressources location = "classpath: / meta-inf / ressources /" mapping = "swagger-ui.html" /> <mvc: ressources location = "classpath: / meta-inf / ressources / webjars /" mapping = "/ webjars / **" />
Remarque: Je ne publierai pas la configuration de base SpringMVC. Il convient de noter que si vous voyez l'interface Swagger-Ui.html sortir, mais c'est vide, veuillez vérifier la configuration de l'intercepteur dans votre web.xml. Vous devez d'abord intercepter SpringMVC, puis l'interface s'affichera.
3. Ensuite, il y a la classe de configuration de Swagger2:
@ Configuration @ ActivedWagger2Public Class SwaggerConfig étend webmvcconfigurationsupport {@bean public docket createstapi () {return new Docket (documentationType.swagger_2) .apiinfo (apiinfo ()) .select () .apis (requestHandlerselectors.basePackage ("net.laoyeyey.yyblog")) .paths (pathselectors.any ()) .build (); } private apiinfo apiinfo () {return new apiinfobuilder () .title ("yyblog project restful apis") .deScription ("yyblog project API Interface Documentation") .Version ("1.0") .build (); }}Remarque: Si les chemins peuvent être ajustés à PathSelectors.None () En production, il n'affiche pas toutes les informations d'interface;
4. Configuration des informations d'interface
C'est-à-dire configurer les informations d'interface pertinentes dans le contrôleur SpringMVC
@ Contrôleur @ requestmapping (value = "Aitou") @ api (Description = "Test Service-Account Information Query") Classe publique DailyOperationDataController {Logger Logger = Logger.getLogger (DailyOperationDataCtroller.Class); @Autowired Private DailyOperationDataService DailyOperationDataService; / * * @APiOperation (valeur = "Interface Description", httpMethod = "Méthode de la demande d'interface", réponse = "Interface return Paramet Type", notes = "Interface Release Notes" * @APiparam (required = "est le paramètre requis", name = "Account Name", Value = "Parameter Specific Description" * / @apiOperation (value = "Compte Information Query Interface") = {RequestMethod.post, requestMethod.get}, value = "/ query / dailydata / {datadate}") @ResponseBody DailyOperationDatadto GetDailyReportByDataDate (@pathvariable ("datadate") String Datadate) {try {return dailyDat (Exception e) {logger.Error (e.getMessage (), e);Remarque: Habituellement, Swagger2 affiche toutes les interfaces sous le package de scan. Ici, je suis l'interface externe pour être un package séparé pour éviter d'afficher trop d'interfaces. Bien sûr, la méthode d'interface peut également l'empêcher de s'afficher. Vous pouvez voir les annotations pertinentes ci-dessous.
Certaines notes couramment utilisées
@API: utilisé sur une classe pour illustrer la fonction de la classe
@ApiOperation: utilisé dans les méthodes pour illustrer la fonction des méthodes
@APIimplicitParams: Utilisé pour inclure un ensemble de descriptions de paramètres sur la méthode
@APIimplicitParam: Utilisé dans l'annotation @APIIMPLICtParams, spécifiez divers aspects d'un paramètre de demande Paramype: où placer le paramètre ・ En-tête -> Obtenez le paramètre de demande: @RequestHeader
・ Query -> Demande Acquisition des paramètres: @RequestParam
・ Path (pour l'interface RESTFul) -> Obtenez les paramètres de demande: @Pathvariable
・ Corps (non couramment utilisé)
・ Forme (pas couramment utilisée)
Nom: Paramètre Nom DataType: Type de paramètre requis: si le paramètre doit être passé Valeur: Paramètre Signification DefaultValue: Paramètre Valeur par défaut
@APiRESPONSES: Utilisé pour représenter un ensemble de réponses
@APiResponse: utilisé dans @APiResponses, il est généralement utilisé pour exprimer un code de réponse d'erreur: un nombre, comme 400
Message: Message, tel que "le paramètre de demande n'est pas rempli"
Réponse: classe qui lance l'exception
@Apiparam: Description du paramètre unique
@APIMODEL: Décrivez les informations d'un modèle et utilise des objets pour recevoir des paramètres (ceci est généralement utilisé lors de la création de messages, en utilisant des scénarios @Requestbody, et lors de la demande de paramètres ne peut pas être décrit à l'aide de @APIIMPLICTPARAM ANNOTATION)
@Apimodelproperty: décrivez les propriétés d'un modèle
@Apiproperty: Lorsque vous utilisez un objet pour recevoir des paramètres, décrivez un champ de l'objet
@APIIGNORE: Utilisez cette annotation pour ignorer cette API
Fondamentalement, c'est tout ce qui précède. N'est-ce pas très facile? Voyons l'image de l'effet ci-dessous
2. Utilisez le Springboot pour intégrer Swagger2
Ce qui précède à l'aide de SpringMVC traditionnelle pour intégrer Swagger2. Parlons de la récente méthode populaire Springboot. En fait, les principes sont les mêmes.
1. Dépendance Maven
<! - Springfox Dependency -> <Dedency> <GroupId> io.springfox </proncId> <ArtifActid> Springfox-Swagger2 </ ArfactId> <Dersion> 2.7.0 </DERNIFRIMITION> </DENDENCE> <Dedency> <ProupId> IO.SpringFox </proupId> <ArtifActid> SpringFox-Swagger-Ui </ Artiford> <version> 2.7.0 </ version> </ dépendance>
Il s'agit de l'utilisation interne de mon projet personnel que j'ai écrit récemment en utilisant Springboot, et la version utilisée 2.7.0 est utilisée dans la version.
2. Ajouter une configuration de ressources statique
@ConfigurationPublic Class webmvcConfig étend webmvcconfigurerAdapter {/ ** * configurer le chemin de ressource statique et le chemin pour télécharger le fichier * * @param registre * / @Override public void addResourceHandlers (ResourceHandlerRegistry Registry) { registry.addreSourceHandler ("/ static / **"). addResourceLocations ("classPath: / static /"); registry.addresourceHandler ("/ upload / **"). addResourceLocations (Environment.getProperty ("Spring.Resources.Static-Locations")); / * Swagger-Ui * / Registry.AddreSourceHandler ("Swagger-Ui.html"). AddResourceLocations ("ClassPath: / Meta-Inf / Resources /"); registry.addreSourceHandler ("/ webjars / **"). addResourceLocations ("classpath: / meta-inf / ressources / webjars /"); }}En fait, ce ne sont que les deux dernières phrases. Si vous ne configurez pas cela, vous verrez une erreur de 500 ou 404 lorsque vous visitez Swagger-Ui.html. Si vous ne vous en souvenez pas, ce devrait être 404.
3. Classe de configuration Swagger2
Comme ce qui précède, il n'y a essentiellement aucune différence
@ Configuration @ ActivedWagger2 @ activerwebmvcpublic class SwaggerConfig étend webmvcConFigurationsUpport {@bean public Docket Createrestapi () {return new Docket (DocumentationType.Swagger_2) .APIInfo (apiinfo ()) .Select () .apis (requestHandlerselectors.basePackage ("net.laoyeye.yyblog.web.fronttend")) .paths (pathselectors.none ()) .build (); } private apiinfo apiinfo () {return new apiinfobuilder () .title ("yyblog project restful apis") .deScription ("yyblog project api document") .Version ("1.0") .build (); }}Notez que j'ai un problème avec le chemin ci-dessus. La copie n'affiche directement pas l'API (# ^. ^ #)
4. Configuration de l'interface
/ ** * Contrôleur d'article de la réception * @Author Grandpa dans le magasin de commodité * @Date 5 mai 2018 * @website www.laoyeye.net * / @ api (description = "Article Query") @ contrôleur @ requestmaping ("/ article") public class articleController {@Autowired Private ArticleServiceservice; @Autowired Private SettingService SettingService; @Autowired Private Cateservice Catesservice; @Autowired private tagReferservice tagReferService; @Autowired Private UserService UserService; @Autowired Private Articlemapper Articlemapper; @Autowired Private CommentaireService CommentaireService; @ApiOperation (value = "Interface de requête d'article") @APIIMPLICtParam (name = "id", value = "Article ID", Obligatoire = true, dataType = "long") @getMapping ("/ {id}") public String index (modèle modèle, @pathvariable ("id") Long ID) {try {ArticleService.UpDateViewsById (id); } catch (exception ignore) {} list <fixed paraming> paramètres = settingService.Listall (); Map <string, object> map = new hashmap <string, object> (); pour (paramètre de paramètre: paramètres) {map.put (setting.getcode (), setting.getValue ()); } Article Article = ArticleService.getArticleById (ID); Model.AddAttribute ("Paramètres", MAP); Model.AddAttribute ("Catelist", catégorieService.ListAllCate ()); Model.AddAttribute ("Article", article); Model.AddAttribute ("Tags", TagReferService.ListNameByArticleId (article.getId ())); Model.AddAttribute ("auteur", userService.getNickNameById (article.GetAuthorid ())); // Change Model.AddAttribute ("Articles", Articlemapper.ListarticleByTitle (null)); Model.AddAttribute ("similaires", articlemapper.ListarticleByTitle (null)); CommentQuey Query = new COMMENTQUERY (); query.setlimit (10); query.setpage (1); query.setarticleId (id); Model.AddAttribute ("Commentaires", commentaire.ListCommentByArticleId (Query)); retourner "frontend / article"; } @Apioperation (value = "Interface de requête ArtiClecomment") @postmapping ("/ commentaires") @ResponseBody public dataGridResult Commentaires (commentaire de commentaire) {// Définit la par défaut 10 query.setlimit (10); return commentService.ListCommentByArticleId (Query); } @Apioperation (value = "articlelid") @apiimplicitParam (name = "articleId", value = "articleId", obligé = true, dataType = "long") @postmapping ("/ approuver") @ResponseBody Public YyBlogreseLt Apprave (@requestParam Long ArticleId); }}Enfin, il y a un rendu, le même que ci-dessus.
Quand PathSelectors.None ()
Quand pathselectors.y () est
Il est clair en un coup d'œil si le contenu de l'interface est le rendu, et il est très concis et clair.
Enfin, il semble que j'ai oublié de dire le chemin du document Swagger
Si votre projet est dans le répertoire racine: http: // localhost: 8080 / swagger-ui.html
Si ce n'est pas le répertoire racine, c'est: http: // localhost: 8080 / le nom de votre projet / swagger-ui.html
Ce qui précède est tout le contenu de cet article. J'espère que cela sera utile à l'apprentissage de tous et j'espère que tout le monde soutiendra davantage Wulin.com.