码迷,mamicode.com
首页 > 其他好文 > 详细

项目引入Swagger及使用姿势

时间:2020-05-14 19:07:07      阅读:331      评论:0      收藏:0      [点我收藏+]

标签:resource   author   tor   java   启动   hand   dock   pre   文件   

1.导入pom依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.2</version>
</dependency>

2.添加swagger配置类

package com.demo.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.HashSet;

/**
 * <p>
 * swagger页面展示的配置
 * </p>
 *
 * @author Toby
 * @since 2020/5/13
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        HashSet<String> contentType = new HashSet<>(1);
        contentType.add("application/json");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .consumes(contentType)
                .produces(contentType)
                .select()
            	// 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx-api文档")
                .description("xxx-xx模块api文档")
                .version("1.0")
                .contact(new Contact("xxx项目组","","xxxx@xxx.com"))
                .build();
    }
    

}

:basePackage要改为项目对应的controller目录路径,使用增强功能的话,需要在配置类上加@EnableKnife4j注解,并且在UI界面的个性化设置中开启增强功能。具体增强功能请移步至最后自行查看文档

3.查看UI界面

启动项目后,在浏览器输入http://${host}??{port}/doc.html

4.项目中可能会用到的增强功能

  • 自定义文档

    在resource目录下新建markdown文件夹,在目录下新建.md结尾的file即可。在application.yml中加入以下配置

    knife4j:
      markdowns: classpath:markdown/*
    

    注意:自定义文档说明必须以.md结尾的文件,其他格式文件会被忽略

  • 访问权限控制-生产环境屏蔽Swagger所有资源接口

    之前的项目如果想在正式环境配置中屏蔽Swagger资源的话,是取的spring.profiles.active运行环境作判断,现在只需要在正式的application.yml中加入以下配置即可。

    knife4j:
      production: true
    
  • 访问页面加权控制

    登录需要账号密码,提供简单的basic认证功能,在application.yml中加入以下配置即可。

    knife4j:
      ## 开启Swagger的Basic认证功能,默认是false
      basic:
        enable: true
      ## Basic认证用户名
        username: admin
      ## Basic认证密码
        password: 123456
    

4.注意事项

  • 依赖变更

    ui前端界面显示的依赖更改,com.github.xiaoymin下的springfox-swagger-ui最终版本为1.9.6,之后版本包名更改为knife4j,不同框架集成方式的pom依赖自行查看原文文档。

  • api分组相关,Docket实例不能延迟加载(目前应该用不到,具体多少个算多也不清楚,知道即可。)

    springfox默认会把所有api分成一组,这样访问时会在同一个页面里加载所有api列表。这样,如果系统稍大一点,api稍微多一点,页面就会出现假死的情况,所以很有必要对api进行分组。api分组,定义多个RestApi即可,通过groupName作区分。

5.文档地址

knife4j使用教程:https://doc.xiaominfo.com/knife4j/

GitHub地址:https://github.com/xiaoymin/swagger-bootstrap-ui

项目引入Swagger及使用姿势

标签:resource   author   tor   java   启动   hand   dock   pre   文件   

原文地址:https://www.cnblogs.com/tobyhomels/p/12890521.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!