Os documentos da interface externa sempre foram relativamente primitivos e os documentos manuscritos basicamente são transmitidos. Recentemente, descobri um novo brinquedo, que pode economizar muitos problemas na interface.
O Swagger é uma estrutura conveniente de documentação da API. Ele pode exibir o tipo de interface para o outro desenvolvedor da maneira mais abrangente, evitando o comportamento unilateral e de erro dos documentos manuscritos.
Atualmente, existem dois tipos de arrogância e swagger2. 1 é mais problemático, então você não considera usá -lo. Este artigo registra principalmente duas maneiras pelas quais eu uso o Swagger2 como uma interface externa. Por favor, verifique mais tarde.
1. Use Springmvc tradicional para integrar Swagger2
1. Dependência do Maven
<!-Springfox Dependências-> <Ependency> <PuerpId> com.fasterxml.jackson.core </groupiD> <TRAFACTID> Jackson-core </stutifactId> <versão 2.8.0 </versão </dependency> <pendency> <roupidId> com.fasterxml.jackson.core </GrupoId> <version>2.6.3</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.6.3</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <Versão> 2.4.0 </siers> </dependency> <pendency> <puperid> io.springfox </groupiD> <TRAFACTID> springfox-swagger-ui </artifactId> <versão> 2.4.0 </sipers> </pendence>
2. Adicione uma configuração de mapeamento estático em spring-mvc.xml (na verdade, posso remover isso no meu projeto, não sei qual é a situação):
<!-Swagger estático caminho do arquivo-> <mvc: recursos localizador = "classpath:/meta-inf/resources/" mapping = "swagger-ui.html"/> <mvc: resources Location = "Classpath:/meta-inf/Resources/Webjars/" mapping = "/webjars/**"/>
Nota: Não vou postar a configuração básica do Springmvc. Deve-se notar que, se você vir a interface Swagger-ui.html saindo, mas está em branco, verifique a configuração do interceptador em seu web.xml. Você deve interceptar Springmvc primeiro e, em seguida, a interface será exibida.
3. Depois, há a classe de configuração de Swagger2:
@Configuration @EnableSwagger2Public Classe swaggerConfig estende webmvcConfiguraçõespport {@Bean public Docket CreaterRestapi () {Return new Docket (documentationType.swagger_2) .apiinfo (apiinfo (). Selecione () .apis (requestHandlerElectors.basepackage ("net.laoyeyeyey.yyblog")) .paths (pathSelectors.any ()) .build (); } private apiinfo apiinfo () {return New Apiinfobuilder () .title ("yyblog Project Restful Apis") .Description ("Documentação da interface api do projeto yyblog") .version ("1.0") .build (); }}NOTA: Se os caminhos puderem ser ajustados para o PathSelectors.None () na produção, ele não exibirá todas as informações da interface;
4. Configuração de informações da interface
Ou seja, configure informações de interface relevantes no controlador Springmvc
@Controlador@requestmapping (value = "aitou")@api (description = "teste de serviço de serviço de serviço consulta") public class DailyOperationDatacOntroller {Logger Logger = Logger.getLogger (DailyOperationDatacontroller.class); @AUTOWIRED PRIVADO DIÁRIO DIÁRIO DO MELHO DA DIÁRIO DA CILIALOPERAÇÃO DATATASVEN; / * * @Apioperation (value = "Interface Descrição", httpmethod = "Método da solicitação de interface", resposta = "interface Retorno Tipo de parâmetro", Notes = "Notas de liberação da interface" * @apiparam (requerir) é o parâmetro necessário ", name =" Nome do parâmetro ", value =" Parâmetro específico " */ @APIOPERAÇÃO (Nome =" Nome do parâmetro ", value =" Parâmetro específico " */ @APOPERATION (Value =" = {RequestMethod.post, requestmethod.get}, value = "/query/DailyData/{datAdate}") @Responsebod e) {logger.error (e.getMessage (), e);Nota: Geralmente, o Swagger2 exibe todas as interfaces no pacote de varredura. Aqui eu sou a interface externa para ser um pacote separado para evitar exibir muitas interfaces. Obviamente, o método da interface também pode impedir que ele seja exibido. Você pode ver as anotações relevantes abaixo.
Algumas notas comumente usadas
@Api: usado em uma aula para ilustrar a função da classe
@Apioperation: usado em métodos para ilustrar a função dos métodos
@Apiimplicticparams: usado para incluir um conjunto de descrições de parâmetros no método
@APIImplicitParam: Usado na anotação @APIImplicitParams, especifique vários aspectos de um parâmetro de solicitação Paramtype: onde colocar o parâmetro ・ Cabeçalho -> Obter parâmetro de solicitação: @RequestHeader
・ Consulta -> Aquisição de parâmetros de solicitação: @RequestParam
・ Caminho (para interface RESTful) -> Obtendo parâmetros de solicitação: @PathVariable
・ Corpo (não comumente usado)
・ Formulário (não comumente usado)
Nome: Nome do parâmetro Datatype: Tipo de parâmetro Necessário: Se o parâmetro deve ser passado Valor: Parâmetro Significado DefaultValue: Parâmetro Valor padrão
@Apiresponses: usado para representar um conjunto de respostas
@Apiresponse: Usado em @apiresponses, geralmente é usado para expressar um código de resposta de erro: um número, como 400
Mensagem: Mensagem, como "O parâmetro de solicitação não está preenchido"
Resposta: classe que lança exceção
@Apiparam: descrição de um único parâmetro
@Apimodel: descreva as informações de um modelo e usa objetos para receber parâmetros (isso geralmente é usado ao criar postagens, usando cenários @Requestbody e, ao solicitar parâmetros, não pode ser descrito usando @apiimplicitparam anotação)
@Apimodelproperty: descreva as propriedades de um modelo
@Apiproperty: Ao usar um objeto para receber parâmetros, descreva um campo do objeto
@Apiignore: use esta anotação para ignorar esta API
Basicamente, é tudo acima. Não é muito fácil? Vamos ver a imagem do efeito abaixo
2. Use Springboot para integrar Swagger2
O mencionado acima usando o SpringMVC tradicional para integrar Swagger2. Vamos falar sobre o recente método popular de Springboot. De fato, os princípios são os mesmos.
1. Dependência do Maven
<!--springfox dependency--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <Versão> 2.7.0 </sisters> </dependency>
Este é o uso interno do meu projeto pessoal que escrevi recentemente usando o Springboot, e a versão usada 2.7.0 é usada na versão.
2. Adicione a configuração de recursos estáticos
@ConfigurationPublic Class webmvcConfig estende o webmvcConfigureRAdApter {/ ** * Configure o caminho de recursos estáticos e o caminho para fazer o upload do arquivo * * @param Registry */ @Override publicVoid AddResourceHandlers (RecursoHandlerGistry Registry) {Override Registry.addResourceHandler ("/static/**"). AddResourCelocations ("ClassPath:/static/"); Registry.addResourceHandler ("/upload/**"). AddResourCelocations (Environment.getProperty ("spring.resources.static-locações")); /*swagger-ui*/registry.addresourceHandler ("swagger-ui.html"). addResourcelocations ("classpath:/meta-inf/resources/"); Registry.AddResourceHandler ("/webjars/**"). AddResourCelocations ("ClassPath:/meta-Inf/Resources/Webjars/"); }}De fato, são apenas as duas últimas frases. Se você não configurar isso, verá um erro de 500 ou 404 quando visitar swagger-ui.html. Se você não consegue se lembrar, deve ser 404.
3. Classe de configuração Swagger2
Como acima, basicamente não há diferença
@Configuration@EnableSwagger2@EnableWebmvcpublic Classe SwaggerConfig estende webmvcConfigurationsUpport {@Bean public Docket CreaterRestapi () {Return New Docket (DocumentationType.swagger_2) .apiinfo (Apiinfo (). .apis (requestHandlerElectors.basepackage ("net.laoyeye.yyblog.web.frondend")) .paths (pathSelectors.none ()) .build (); } private apiinfo apiinfo () {return New Apiinfobuilder () .title ("yyblog Project Restful Apis") .Description ("Documento de interface do projeto do projeto API") .version ("1.0") .build (); }}Observe que tenho um problema com o caminho acima. A cópia diretamente não exibe a API (#^.^#)
4. Configuração da interface
/*** Controlador do artigo da recepção* @Author vovô na loja de conveniência* @Date 5 de maio de 2018* @WebSite www.laoyeye.net*/ @api (descrição = "Artigo consulta") @controlador @requestmapping ("/Artigo") public class ArticlOrcontroller {@AUTOWIRED ARTICLICE ("/Article") @Autowired Private SettingService SettingService; @Autowired Private CateService CateService; @AUTOWIRED PRIVADO TAGRERFERSERVICE TAGREFERSERVICE; @AUTOWIRED PRIVADO UserService UserService; @Autowired Private ArticleMapper ArticleMapper; @AUTowired Private CommentService CommentService; @Apioperation (value = "interface do artigo interface") @apiimplicticParam (name = "id", value = "ID do artigo", requerido = true, datatype = "long") @getMapping ("/{id}") public string index (modelo, modelo, @PathVariable (") idi ({try}); } catch (exceção ignorar) {} list <Feting> Settings = SettingService.Listall (); Mapa <string, object> map = new hashmap <string, object> (); para (Configuração de configuração: Configurações) {map.put (Setting.getCode (), Setting.getValue ()); } Artigo = ArticleService.getarticleById (ID); Model.Addattribute ("Configurações", mapa); Model.Addattribute ("Catelist", categoryService.ListallCate ()); Model.Addattribute ("Artigo", artigo); Model.Addattribute ("Tags", tagReferService.ListNameByArticleId (Artigo.getId ())); Model.Addattribute ("Author", UserService.getNickNameById (Artigo.Getauthorid ())); // altere model.addattribute ("artigos", articleMapper.ListarticleByTitle (null)); Model.Addattribute ("Similars", ArticleMapper.ListarticleByTitle (NULL)); Comentário query = new commentQuery (); query.setlimit (10); query.setPage (1); query.setArticleId (id); Model.Addattribute ("Comentários", CommentService.ListCommentByarticleId (consulta)); retornar "front -end/artigo"; } @Apioperation (value = "interface de consulta de articleComment") @PostMapping ("/Comentários") @ResponseBody Public DataGridResult Comentários (comentários de comentários) {// Defina o padrão 10 Query.setlimit (10); return ComementService.ListCommentByArticleId (consulta); } @Apioperation (value = "articlelid") @apiImplicticParam (name = "articleId", value = "articleId", requerir = true, datatype = "long") @PostMapping ("aprove") @ResponseBody Public yyblogresult aprove (@requestParam)) {Return). }}Finalmente, há uma renderização, a mesma que acima.
Quando PathSelectors.None () é
Quando PathSelectors.any () é
Está claro de relance se o conteúdo da interface é a renderização e é muito conciso e claro.
Finalmente, parece que eu esqueci de dizer o caminho para o documento Swagger
Se o seu projeto estiver no diretório raiz: http: // localhost: 8080/swagger-ui.html
Se não for o diretório raiz, é: http: // localhost: 8080/seu nome do projeto/swagger-ui.html
O exposto acima é todo o conteúdo deste artigo. Espero que seja útil para o aprendizado de todos e espero que todos apoiem mais o wulin.com.