Die externen Schnittstellendokumente waren schon immer relativ primitiv, und im Grunde werden handgeschriebene Dokumente weitergegeben. Vor kurzem habe ich ein neues Spielzeug entdeckt, das auf der Benutzeroberfläche viele Probleme sparen kann.
Swagger ist ein bequemer API -Dokumentationsrahmen. Es kann den Schnittstellentyp dem anderen Entwickler auf umfassendste Weise anzeigen und das einseitige und fehlerhafte Verhalten handschriftlicher Dokumente vermeiden.
Derzeit gibt es zwei Arten von Prahlerei und Prahler2. 1 ist schwieriger, so dass Sie es nicht in Betracht ziehen, es zu verwenden. Dieser Artikel erfasst hauptsächlich zwei Möglichkeiten, wie ich Swagger2 als externe Schnittstelle verwende. Bitte überprüfen Sie es später.
1. Verwenden Sie traditionelle SpringMVC, um Swagger2 zu integrieren2
1. MAVEN -Abhängigkeit
<!-Springfox-Abhängigkeiten-> <De vorstellen> <gruppe> com.fasterxml.jackson.core </Groupid> <artifactId> Jackson-Core </artifactID> <version> 2.8.0 </Version> </abhängig> </gruppen> com.fasterxml.jackson <version> 2.6.3 </version> </abhängig> <depe vorstellen> <gruppe> com.fasterxml.jackson.core </Groupid> <artifactid> Jackson-Annotationen </artifactId> <version> 2.6.3 </Version> </abhängig> <Diefency> <gruppe> io.sspringfox </Groupid> <artifactId> Springfox-Swagger2 </artifactId> <version> 2.4.0 </Version> </abhängig> <depeopentcy> <gruppe> io.springfox </Groupid> <artifactId> Springfox-Swagger-UI </artifactid> <version> 2.4.0 </Version> </abhängig> Abhängigkeit>
2. Fügen Sie eine statische Mapping-Konfiguration in Spring-MVC.xml hinzu (ich kann dies in meinem Projekt entfernen, ich weiß nicht, wie die Situation ist):
<!-Swagger statischer Dateipfad-> <MVC: Ressourcen location = "classPath:/meta-inf/ressourcen/" maping = "Swagger-ui.html"/> <mvc: ressourcen location = "classPath:/meta-inf/ressourcen/webjars/" maping = "/webjars/**"/>
Hinweis: Ich werde die grundlegende SpringMVC -Konfiguration nicht veröffentlichen. Es ist zu beachten, dass, wenn Sie sehen, dass die Swagger-Ui.html-Schnittstelle herauskommt, aber leer ist, bitte überprüfen Sie die Konfiguration des Interceptors in Ihrem web.xml. Sie müssen zuerst SpringMVC abfangen, und dann wird die Schnittstelle angezeigt.
3. Dann gibt es die Konfigurationsklasse von Swagger2:
@Configuration @enableWagger2Public Class SwaggerConfig erweitert webmvcconfigurationsupport {@Bean public docket createrestapi () {return New Docket (documentationType.swagger_2) .apiinfo (apiInfo () .Select () .APISHERSELECTORS.BASEPAKEPACKEN (). .Paths (PathSelectors.anan ()) .build (); } private apiInfo apiinfo () {neue apiInfobuilder () .Title ("yyblog restful apis") .Description ("Yyblog -Projekt -API -Schnittstellen -Dokumentation") .version ("1.0") .build (); }}HINWEIS: Wenn Pfade an PathSelectors angepasst werden können.none () in der Produktion, zeigt nicht alle Schnittstelleninformationen an.
4. Konfiguration der Schnittstelleninformationen
Konfigurieren Sie relevante Schnittstelleninformationen im SpringMVC -Controller
@Controller@requestMapping (value = "aitou")@api (Beschreibung = "test Service-Account Information Abfrage") öffentliche Klasse DailyOperationDataconTroller {logger logger = logger.getLogger (DailyOperationDatacontroller.class); @Autowired Private DailyOperationDataService DailyOperationDataService; / * * @Apioperation (value = "Schnittstelle Beschreibung", httpMethod = "Schnittstellenanforderungsmethode", Response = "Schnittstellenrückgabeparameter -Typ", Notizen = "Schnittstellen -Release -Notizen" * @APIPARAM (erforderlich = "ist der Parameter erforderlich", Name = "Parameter Name", Value = "Parameter -Spezifische Beschreibung" */ @APIPICING (VALTEDICTION = "ACTOCTING"). = {RequestMethod.Post, RequestMethod.get}, value = "/query/DailyData/{datAdate}") @RespondeBody public täglicherDatadto getDailyRePortByDatadate (@Pathvariable ("DatadataTaDataDataTaDataDataTaDataTaDataTaDataTaTaTaTaTaTaTaTaTaTaTaTaTaTaTaTaDataTaDataTaDataTaDataTaData" (@Pathvariable) (Ausnahme e) {Logger.Eror (E.getMessage (), e);Hinweis: Normalerweise zeigt Swagger2 alle Schnittstellen unter dem Scan -Paket an. Hier bin ich die externe Schnittstelle, um ein separates Paket zu sein, um zu viele Schnittstellen anzuzeigen. Natürlich kann die Schnittstellenmethode auch verhindern, dass sie angezeigt wird. Sie können die relevanten Anmerkungen unten sehen.
Einige häufig verwendete Notizen
@API: Wird in einer Klasse verwendet, um die Funktion der Klasse zu veranschaulichen
@APIOperation: Wird in Methoden verwendet, um die Funktion von Methoden zu veranschaulichen
@ApiimplicitParams: Wird verwendet, um eine Reihe von Parameterbeschreibungen in die Methode aufzunehmen
@ApiimplicitParam: Geben Sie in der Annotation @APIimPlictarams verschiedene Aspekte eines Anforderungsparameters an.
・ Abfrage -> Anfrage Parameter Akquisition: @RequestParam
・ Pfad (für eine rastful -Schnittstelle) -> Anforderungsparameter erhalten: @PathVariable
・ Körper (nicht häufig verwendet)
・ Form (nicht häufig verwendet)
Name: Parameter Name Datentyp: Parametertyp erforderlich: Ob der Parameter übergeben werden muss, Wert: Parameter Bedeutung StandardValue: Parameter Standardwert
@Apiresponses: Wird verwendet, um eine Reihe von Antworten darzustellen
@Apiresponse: Wird in @APIResponses verwendet, wird es im Allgemeinen verwendet, um einen Fehlerantwortcode auszudrücken: eine Nummer wie 400
Nachricht: Nachricht wie "Der Anforderungsparameter wird nicht ausgefüllt"
Antwort: Klasse, die Ausnahme ausgelegt hat
@Apiparam: Einzelparameter Beschreibung
@Apimodel: Beschreiben Sie die Informationen eines Modells und verwenden Objekte, um Parameter zu empfangen (dies wird normalerweise beim Erstellen von Beiträgen, mit @RequestBody -Szenarien verwendet und bei der Anforderung von Parametern nicht mit @APIimPlictCaram -Annotation beschrieben werden)
@ApimodelProperty: Beschreiben Sie die Eigenschaften eines Modells
@APIPROPERTY: Beschreiben Sie bei Verwendung eines Objekts zum Empfang von Parametern ein Feld des Objekts
@APIIGNORE: Verwenden Sie diese Annotation, um diese API zu ignorieren
Grundsätzlich ist alles oben. Ist es nicht sehr einfach? Lassen Sie uns das Bild unten sehen
2. Verwenden Sie Springboot, um Swagger2 zu integrieren2
Die oben genannten unter Verwendung herkömmlicher SpringMVC, um Swagger2 zu integrieren2. Sprechen wir über die jüngste beliebte Springboot -Methode. Tatsächlich sind die Prinzipien gleich.
1. MAVEN -Abhängigkeit
<!-Springfox Depellentcy-> <De vorstellen> <GroupId> io.springfox </GroupId> <artifactId> Springfox-Swagger2 </artifactid> <version> 2.7.0 </Version> </abhängig> <Epapting> <gruppe io.springfox </gruppe <artifactid> <artifactid> -Schagger-artifox </artifact> <artifactid> <version> 2.7.0 </Version> </abhängig>
Dies ist die interne Verwendung meines persönlichen Projekts, das ich kürzlich mit Springboot geschrieben habe, und die Version 2.7.0 wird in der Version verwendet.
2. Fügen Sie die Konfiguration der statischen Ressourcen hinzu
@ConfigurationPublic Class webmvcconfig erweitert webmvcconFigurerAdapter {/ ** * Konfigurieren Sie den statischen Ressourcenpfad und den Pfad zum Hochladen der Datei * * @param Registry */ @Override public void addresourceHandlers (ResourceHandlerregistry -Registrierung) { 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/ressourcen/"); Registry.AddresourceHandler ("/webjars/**"). AddResourcelocations ("ClassPath:/meta-inf/ressourcen/webjars/"); }}Tatsächlich sind es nur die letzten beiden Sätze. Wenn Sie dies nicht konfigurieren, sehen Sie einen Fehler von 500 oder 404, wenn Sie Swagger-ui.html besuchen. Wenn Sie sich nicht daran erinnern können, sollte es 404 sein.
3.. Swagger2 -Konfigurationsklasse
Wie die obigen gibt es im Grunde keinen Unterschied
@Configuration@enableWagger2@enableWebmvcPublic Class SwaggerConfig erweitert webmvcconFigurationsupport {@Bean public docket createrestapi () {neuer Docket zurückgeben (documentationType.swagger_2) .APIInfo (apiInfo () .Select () () .Select () () () .Select () () (). .APIS (RequestHandlerSelectors.Basepackage ("net.laoyeye.yyblog.Web.Frontend")) .Paths (PathSelectors.none ()) .build (); } private apiInfo apiinfo () {neue apiInfobuilder () .Title ("Yyblog -Projekt restful apis") .Description ("Yyblog -Projekt -API -Schnittstellen -Dokument") .version ("1.0") .build (); }}Beachten Sie, dass ich ein Problem mit dem obigen Pfad habe. Die Kopie zeigt die API (#^.^#) Nicht an
4. Schnittstellenkonfiguration
/*** Artikel Controller an der Rezeption* @Author Opa im Convenience Store* @date 5. Mai 2018* @Website www.laoyeye.net*/ @api (Beschreibung = "Artikel query") @Controller @RequestMapping ("/Artikel") öffentliche ArticleController -Artikeln für private Artikeln für private Artikeln. @Autowired Private SettingService SettingService; @Autowired Private CateService CateService; @Autowired Private Tagreferservice Tagreferservice; @Autowired Private UserService UserService; @Autowired Private Articlemapper Articlemapper; @Autowired Private KommentareService KommentarService; @Apioperation (value = "article query interface") @apiimPlictaram (name = "id", value = "article id", fordert = true, dataType = "long") @getMapping ("/{id}") public String Index (Modellmodell, @PathVariable ("id") long id id) {{artlesVice.UpDate.UpDate.UpDate.UpDateVice ({articleService.Update.UpDate.Update); } catch (Exception Ignore) {} List <Seting> Einstellungen = SettingService.Listall (); Karte <String, Objekt> map = new HashMap <String, Object> (); für (Einstellungseinstellung: Einstellungen) {map.put (Setting.getCode (), Einstellung.getValue ()); } Article article = tectionService.getArticleById (id); model.addattribute ("Einstellungen", Karte); model.addattribute ("Katelist", categoryService.listallcate ()); model.addattribute ("Artikel", Artikel); model.addattribute ("tags", modreferservice.listnamebyarticleId (article.getId ())); model.addattribute ("Autor", userService.getNicknamebyId (article.getAuthorid ())); // Model.AddAttribute ("Artikel", articlemapper.ListArticleByTitle (null)); model.addattribute ("ähnelt", articlemapper.ListArticleByTitle (null)); Kommentar query = neuer Kommentar (); query.setLimit (10); query.setPage (1); query.setArticleId (id); model.addAttribute ("Kommentare", commentesService.listCommentByArticleId (Abfrage)); Rückgabe "Frontend/Artikel"; } @Apioperation (value = "articlecomment query interface") @postmapping ("/comments") @ResponseBody public datagridResult Kommentare (Kommentarabfrage) {// Setzen Sie die Standard 10 query.setLimit (10); return cententService.listCommentByArticleId (Abfrage); } @Apioperation (value = "articlelid") @APiimPlictaram (name = "artikelId", value = "artikelId", fordert = true, dataType = "long") @PostMapping ("/genehmigen Sie") @RespespodeBody public yybloGresult Arever (@RequeStaram long bodyid) {artikel artikel) {{{{{{oder }}Schließlich gibt es ein Rendering, genauso wie oben.
Wenn pathelectors.none () ist
Wenn pathelectors.any () ist
Auf einen Blick ist klar, ob der Schnittstelleninhalt das Rendering ist, und es ist sehr präzise und klar.
Schließlich scheint es, dass ich vergessen habe, den Weg zum Prahlerdokument zu sagen
Wenn sich Ihr Projekt im Stammverzeichnis befindet: http: // localhost: 8080/swagger-ui.html
Wenn es nicht das Root-Verzeichnis ist, ist es: http: // localhost: 8080/Ihr Projektname/Swagger-ui.html
Das obige ist der gesamte Inhalt dieses Artikels. Ich hoffe, es wird für das Lernen aller hilfreich sein und ich hoffe, jeder wird Wulin.com mehr unterstützen.