软件下载

swagger使用详解（Swagger介绍与使用）

软件下载 投稿 2022-06-11 10:21:21 浏览

swagger基于代码生成文档很强悍了，但是在接口很多的时候swagger原生的ui界面就不是很好展现，这个时候就有人来制作符合国人习惯的UI增强包了，那就是knife4j-spring-ui，knife4j-spring-ui的前生是小有名气的swagger-bootstrap-ui.knife4j-spring-ui界面更好看，而且进行了集成封装使用更简单。

1. 开发环境

  • JDK 1.8
  • SpringBoot 2.1.18

2. 添加Maven依赖

<!-- Swagger3 始 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!-- springfox swagger3.x 整合Knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
            <!-- 排除一些与swagger冲突的包 -->
            <exclusions>
                <exclusion>
                    <artifactId>swagger-annotations</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>swagger-models</artifactId>
                    <groupId>io.swagger</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 引入swagger-bootstrap-ui包 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.5</version>
        </dependency>
        <!-- 更改spring-plugin-core版本，解决与swagger导包冲突问题 -->
        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-metadata</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>
        <!-- Swagger3 终 -->

3. 添加Swagger配置类

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    /**
     * 创建API http:IP:端口号/swagger-ui/index.html 原生地址 http:IP:端口号/doc.html
     * bootStrap-UI地址
     */
    @Bean
    public Docket restAuthApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("鉴权接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.auth"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    @Bean
    public Docket restCaptchaApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("验证码接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.captcha"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    @Bean
    public Docket restBaseApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("基础接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.sys"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    @Bean
    public Docket restFlowApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("工作流接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.flow"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    @Bean
    public Docket restWeatherApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("天气接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.weather"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    @Bean
    public Docket restDingtalkApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("钉钉接口")
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.lucksoft.dingtalk"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http")).securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    /**
     * 支持的通讯协议集合
     * 
     * @param type1
     * @param type2
     * @return
     */
    private Set<String> newHashSet(String type1, String type2) {
        Set<String> set = new HashSet<>();
        set.add(type1);
        set.add(type2);
        return set;
    }

    /**
     * 认证的安全上下文
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add(new ApiKey("access_token", "access_token", "header"));
        return securitySchemes;
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts
                .add(SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.any()).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("接口文档")
                // 描述
                .description("描述")
                // 作者信息
                .contact(new Contact("Jonny", "https://www.baidu.com", "lwhou.hn@163.com"))
                // 版本
                .version("版本号:V.1")
                //协议
                .license("The Apache License")
                //协议url
                .licenseUrl("http://www.baidu.com")
                .build();
    }

}

4. 实体类使用Swagger

在接口类上添加@Api(tags = "操作接口")，tags的值是该类的作用，在文档页面会显示，value不会显示
在需要生成文档的接口上添加注解@ApiOperation
对请求参数添加@ApiParam
@ApiModel("角色持久化类")
@Data
@EqualsAndHashCode(callSuper=true)
public class SysRole extends DocEntity{

    @ApiModelProperty(value = "业务id")
    private String doctypeid;

    @ApiModelProperty(value = "所属分类id")
    private String classifyid;

    @ApiModelProperty(value = "角色名称")
    private String name;

    @ApiModelProperty(value = "角色描述")
    private String descr;
    
}

5. 控制器类使用Swagger

@Api(tags="角色接口")
@RestController
public class SysRoleController {
    
    @Autowired
    private SysRoleService sysRoleService;
    @Autowired
    private BaseSysService baseSysService;
    
    /**
     * 查询所有带分页角色管理
     * @param condition 查询条件对象
     * @return List<SysRoleParam>
     */
    @ApiOperation(value = "查询所有带分页角色") 
    @RequestMapping("/readAll")
    @PageableAnnotation
    public List<SysRoleParam> readAll(SysRoleParam condition){
        return sysRoleService.readAll(condition);
    }
    
    /**
     * 查询所有无分页角色管理
     * @param condition 查询条件对象
     * @return List<SysRoleParam>
     */
    @ApiOperation(value = "查询所有带分页角色") 
    @RequestMapping("/readAllNoPage")
    public List<SysRoleParam> readAllNoPage(SysRoleParam condition){
        return sysRoleService.readAll(condition);
    }
    
    /**
     * 查询单条角色管理
     * @param condition 查询条件对象
     * @return SysRoleParam
     */
    @ApiOperation(value = "查询单条角色")
    @GetMapping("/readOne")
    public SysRoleParam readOne(SysRoleParam condition) {
        return sysRoleService.readOne(condition);
    }
    
    /**
     * 查询单条角色管理
     * @param id 主键编号
     * @return SysRoleParam
     */
    @ApiOperation(value = "查询单条角色")
    @GetMapping("/readOneById")
    public SysRoleParam readOneById(String id) {
        return sysRoleService.readOneById(id);
    }
    
    /**
     * 添加角色管理
     * @param entityDto 添加对象
     * @return SysRoleParam
     */
    @ApiOperation(value = "添加角色") 
    @PostMapping("/add")
    public SysRoleParam add(@RequestBody SysRoleParam entityDto) {
        return sysRoleService.add(entityDto);
    }
    
    /**
     * 修改角色管理
     * @param entityDto 修改对象
     * @return void
     */
    @ApiOperation(value = "修改角色") 
    @PostMapping("/update")
    public void update(@RequestBody SysRoleParam entityDto) {
        sysRoleService.update(entityDto);
    }
    
    /**
     * 删除角色管理
     * @param entityDto 删除对象（delList包含多个对象主键集合）
     * @return void
     */
    @ApiOperation(value = "删除角色") 
    @PostMapping("/delete")
    public void delete(@RequestBody SysRoleParam condition){
        sysRoleService.delete(condition.getDelList());
    }
    
    /**
     * 拖拽排序
     * @param entityDto
     */
    @ApiOperation(value = "拖拽排序") 
    @PostMapping("updateDrag")
    public void dragSort(@RequestBody SysRoleParam entityDto) {
        sysRoleService.dragSort(entityDto);
    }
    
}

6. 成果展示

启动服务后，就可以查看在线文档了，本地服务的地址是http://localhost:8080/api/doc.html ，还可以通过Try it out 来测试。

  • 文档分组
五、Swagger介绍与使用（Spring Boot整合Knife4j）

 


五、Swagger介绍与使用（Spring Boot整合Knife4j）

 


五、Swagger介绍与使用（Spring Boot整合Knife4j）

 


五、Swagger介绍与使用（Spring Boot整合Knife4j）

 


五、Swagger介绍与使用（Spring Boot整合Knife4j）

「真诚赞赏，手留余香」

求资源网

真诚赞赏，手留余香

使用微信扫描二维码完成支付

转载请注明：首页 > 投稿 » swagger使用详解（Swagger介绍与使用）

上一篇 : mysql索引总结
下一篇 : 什么是注解?（为什么要使用注解）
你可能喜欢:
继续浏览有关编程的文章
发表评论
留言与评论（共有 0 条评论）
   
验证码：
版权声明

求资源网所发布的一切破解补丁,软件,以及其他分析文章仅限用于学习和研究目的；不得将上述内容用于商业或者非法用途。
否则，一切后果请用户自负。本站信息来自网络，版权争议与本站无关。您必须在下载后的24个小时之内，从您的电脑中彻底删除上述内容。如果您喜欢该程序，请支持正版软件，购买注册，得到更好的正版服务。如有侵权请邮件与我们联系处理。

热门软件
热评软件
随机软件
热门搜索
Copyright Your WebSite.Some Rights Reserved.|网站地图
鄂ICP备2022003045号-2 |