Los documentos de la interfaz externa siempre han sido relativamente primitivos, y básicamente se pasan documentos escritos a mano. Recientemente, descubrí un nuevo juguete, que puede ahorrar muchos problemas en la interfaz.
Swagger es un conveniente marco de documentación de API. Puede mostrar el tipo de interfaz al otro desarrollador de la manera más integral, evitando el comportamiento unilateral y de error de los documentos escritos a mano.
Actualmente hay dos tipos de arrogancia y swagger2. 1 es más problemático, por lo que no considera usarlo. Este artículo registra principalmente dos formas en que uso Swagger2 como interfaz externa. Por favor revise más tarde.
1. Use SpringMVC tradicional para integrar swagger2
1. Dependencia de Maven
< <Versión> 2.6.3 </Version> </Dependency> <Spendency> <MoupRid> com.fasterxml.jackson.core </groupid> <artifactid> Jackson-annotations </arfactid> <versión> 2.6.3 </versión> </dependencia> <pendency> <uproupid> io.springfox </groupid> <AtifactId> Springfox-Swagger2 </arfactid> <versión> 2.4.0 </versión> </pendency> <pendency> <uproupid> io.springfox </proupid> <artifactid> springfox-swagger-ui </artifactid> <versión> 2.4.0 </serspetence> </pendency>
2. Agregue una configuración de mapeo estático en Spring-MVC.XML (en realidad, puedo eliminar esto en mi proyecto, no sé cuál es la situación):
<
Nota: No publicaré la configuración básica de SpringMVC. Cabe señalar que si ve la interfaz swagger-ui.html saliendo, pero está en blanco, verifique la configuración del interceptor en su web.xml. Debe interceptar SpringMVC primero, y luego se mostrará la interfaz.
3. Luego está la clase de configuración de Swagger2:
@Configuration @habilswagger2public class swaggerConfig extiende webMVCConfigurationsUpport {@Bean Public Docket creeaterestapi () {return New Docket (DocumentationType.swagger_2) .ApiInfo (apiInfo ()) .select () .apis (requestlerselectors.basepackage ("net.LAYEYLEG"). .paths (PathSelectors.any ()) .Build (); } private apiinfo apiInfo () {return new apiInfobuilder () .title ("yyblog proyecto RESTFUL APIS") .Description ("YYBLOG Project API Interface Documentation") .Version ("1.0") .Build (); }}Nota: Si las rutas se pueden ajustar a PathSelectores.none () en producción, no muestra toda la información de la interfaz;
4. Configuración de la información de la interfaz
Es decir, configure la información de la interfaz relevante en el controlador SpringMVC
@Controlador@requestmapping (value = "aitou")@api (description = "prueba de servicio de servicio de información") clase pública DailyOperationDataController {logger logger = logger.getLogger (DailyOperationDataController.class); @AutoWired Private DailyOperationDataService DailyOperationDataService; / * * * @Apioperation (value = "Descripción de la interfaz", httpmethod = "método de solicitud de interfaz", respuesta = "Tipo de parámetro de retorno de interfaz", notas = "Nota de liberación de interfaz" * @apiparam (requerido = "es el parámetro requerido", name = "Nombre de parámetro", Value = "Descripción específica del parámetro" */ @apioperation (valor = "Información de la cuenta de la cuenta de la cuenta") = {Requestmethod.post, requestmethod.get}, value = "/query/dayayData/{datADATE}") @ResponseBody public DailyOperationDatadto getDailyReportByDataDate (@PathVariable ("DataDate") String DataDate) (Excepción e) {logger.error (e.getMessage (), e);Nota: Por lo general, Swagger2 mostrará todas las interfaces debajo del paquete de escaneo. Aquí soy la interfaz externa para ser un paquete separado para evitar mostrar demasiadas interfaces. Por supuesto, el método de interfaz también puede evitar que se muestre. Puede ver las anotaciones relevantes a continuación.
Algunas notas de uso común
@Api: se usa en una clase para ilustrar la función de la clase
@Apioperación: se usa en métodos para ilustrar la función de los métodos
@ApiimpliceTParams: se usa para incluir un conjunto de descripciones de parámetros en el método
@ApiimpliceTparam: se usa en la anotación @apiimpliceTparams, especifique varios aspectos de un parámetro de solicitud paramtype: dónde colocar el parámetro ・ encabezado -> obtener parámetro de solicitud: @requestheader
・ Consulta -> Solicitud de adquisición de parámetros: @RequestParam
・ Ruta (para interfaz RESTFUL) -> Obtener parámetros de solicitud: @PathVariables
・ Cuerpo (no se usa comúnmente)
・ Forma (no se usa comúnmente)
Nombre: Nombre del parámetro Tipo de datos: Tipo de parámetro Requerido: si el parámetro debe ser aprobado Valor: Parámetro Significado DefaultValue: Valor predeterminado del parámetro
@Apirosponses: se usa para representar un conjunto de respuestas
@Apiresponse: utilizado en @apirosponses, generalmente se usa para expresar un código de respuesta de error: un número, como 400
Mensaje: Mensaje, como "El parámetro de solicitud no se completa"
Respuesta: clase que arroja excepción
@Apiparam: descripción de un solo parámetro
@Apimodel: Describa la información de un modelo y usa objetos para recibir parámetros (esto generalmente se usa al crear publicaciones, usando @RequestBody Scenarios, y al solicitar parámetros no se puede describir usando la anotación @apiimpliceParam)
@Apimodelproperty: Describa las propiedades de un modelo
@Apiproperty: cuando use un objeto para recibir parámetros, describa un campo del objeto
@Apiignore: usa esta anotación para ignorar esta API
Básicamente, es todo lo anterior. ¿No es muy fácil? Veamos la imagen del efecto a continuación
2. Use Springboot para integrar Swagger2
Lo mencionado anteriormente usando SpringMVC tradicional para integrar Swagger2. Hablemos sobre el reciente método popular springboot. De hecho, los principios son los mismos.
1. Dependencia de Maven
< <Versión> 2.7.0 </versión> </pendency>
Este es el uso interno de mi proyecto personal que escribí recientemente usando SpringBoot, y la versión utilizada 2.7.0 se usa en la versión.
2. Agregar configuración de recursos estáticos
@ConfigurationPublic Class WebMVCCONFIG extiende WebMVCConfigurerAdapter {/ ** * Configurar la ruta de recursos estáticos y la ruta para cargar el archivo * * @param Registry */ @Override public void AddResourceHandlers (Registry de ResourceHanderRegistry) { 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/recursos/"); Registry.AddResourceHandler ("/webJARS/**"). AddResourCelocations ("classpath:/meta -inf/recursos/webjars/"); }}De hecho, son solo las dos últimas oraciones. Si no configura esto, verá un error de 500 o 404 cuando visite swagger-ui.html. Si no puede recordarlo, debería ser 404.
3. Clase de configuración de Swagger2
Como lo anterior, básicamente no hay diferencia
@Configuration@habilswagger2@enablewebmvcpublic swaggerConfig extiende WebMVCConfigurationsUpport {@Bean Public Docket creeaterestapi () {return New Docket (DocumentationType.swagger_2) .apiinfo (apiinfo ().) .Select () .APIS (requestHandLerLectors.BasePackage ("net.laoyeye.yyblog.web.frontend")) .paths (pathSelectors.none ()) .Build (); } private apiInfo apiInfo () {return new apiInfobuilder () .title ("yyblog proyecto RESTFUL APIS") .Description ("Documento de interfaz de API del proyecto YYBLOG") .Version ("1.0") .Build (); }}Tenga en cuenta que tengo un problema con la ruta anterior. La copia directamente no muestra la API (#^.^#)
4. Configuración de la interfaz
/*** Controlador de artículo de recepción* @Author Grandpa en la tienda de conveniencia* @Date 5 de mayo de 2018* @Website www.laoyeye.net*/ @api (descripción = "consulta de artículo") @controlador @requestmapping ("/artículo") public class Articlecontroller {@aUtowired Artatleservice Articles; @AUTOWIREDEDIRD Settingservice Settingservice; @Autowired privado Cateservice Cateservice; @AUtowired TagReferservice TagReferservice; @AutoWired private UserSerervice UserService; @Autowired Private Articlemapper Articlemapper; @AutoWired Commentarservice CommentarsService; @Apioperation (valor = "interfaz de consultas de artículo") @apiimpliceTparam (name = "id", value = "Artículo id", requerido = true, datatype = "long") @getmapping ("/{id}") public string index (modelo modelo, @pathvariable ("id") largo id) {intit {artathereService.updateviews byid (id); } capt (excepción ignore) {} list <tacting> settings = settingservice.listall (); Map <string, object> map = new HashMap <String, Object> (); para (configuración de configuración: configuración) {map.put (setting.getCode (), setting.getValue ()); } Artículo Artículo = ArticlesService.GetAtilyById (id); Model.Addattribute ("Configuración", MAP); modelo.addattribute ("catelist", categoryService.ListallCate ()); model.addattribute ("artículo", artículo); Model.addattribute ("Tags", TagReferservice.ListNameByArticleId (Artículo.getId ())); model.addattribute ("autor", UserService.getNickNameById (Artículo.getAuthorId ())); // Cambiar model.addattribute ("Artículos", Articlemapper.listarticleBytitle (NULL)); Model.Addattribute ("Simils", Articlemapper.listarticleBytitle (NULL)); CommentQuery Query = new Communtequery (); query.setLimit (10); query.setPage (1); Query.SetArticleId (id); Model.addattribute ("Comentarios", Commentservice.listcommentByArticleId (consulta)); devolver "frontend/artículo"; } @Apioperation (valor = "interfaz de consulta de articlecomment") @PostMapping ("/comentarios") @ResponseBody Public DataGridResult Comments (CommentQuery Query) {// Establezca la consulta 10 predeterminada.setLimit (10); devolver comentarios service.listcommentByArticleId (consulta); } @ApiOperation(value="ArticleLid") @ApiImplicitParam(name = "articleId", value = "ArticleID", required = true, dataType = "Long") @PostMapping("/approve") @ResponseBody public YYBlogResult approve(@RequestParam Long articleId) { return articleService.updateApproveCntById(articleId); }}Finalmente, hay una representación, lo mismo que arriba.
Cuando PathSelectors.none () es
Cuando PathSelectores.Aly () es
Está claro de un vistazo si el contenido de la interfaz es la representación, y es muy conciso y claro.
Finalmente, parece que olvidé decir el camino hacia el documento de Swagger
Si su proyecto está en el directorio raíz: http: // localhost: 8080/swagger-ui.html
Si no es el directorio raíz, es: http: // localhost: 8080/su nombre de proyecto/swagger-ui.html
Lo anterior es todo el contenido de este artículo. Espero que sea útil para el aprendizaje de todos y espero que todos apoyen más a Wulin.com.