【Swagger用法】Swagger的使用方法、配置相关内容和简单介绍

本文目录一、Swagger前言二、使用方法方法1：使用第三方的依赖方法2：使用官方依赖三、swagger常用的API一、Swagger前言1、是一款让你更好的书写API文档的规范且完整框架。2、用于提供描述、生产、消费和可视化的RESTful Web Service。3、是由庞大工具集合支撑的形式化规范。Swagger是一个规范和完整的框架，用于生成、描...

No8g攻城狮

1755人浏览 · 2020-04-26 18:08:03

No8g攻城狮 · 2020-04-26 18:08:03 发布

本文目录

一、Swagger前言

1、是一款让你更好的书写API文档的规范且完整框架。

2、用于提供描述、生产、消费和可视化的RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

Swagger的作用：

1、接口的文档在线自动生成。

2、功能测试。

Swagger是一组开源项目，其中主要要项目如下：

1、Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2、Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3、Swagger-js: 用于JavaScript的Swagger实现。

4、Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5、Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6、Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、使用方法

方法1：使用第三方的依赖

（懒人的方法，只需2步）（这是一个依赖集合，添加一个即可引入Swagger所使用的全部依赖）

步骤1、在pom.xml文件中添加第三方swagger依赖

<dependency>
   <groupId>com.spring4all</groupId>
   <artifactId>swagger-spring-boot-starter</artifactId>
   <version>1.9.0.RELEASE</version>
</dependency>

步骤2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用了。

拓展：

拓展2：GitHub上swagger依赖实现的项目：https://github.com/SpringForAll/spring-boot-starter-swagger 这里面有详细的讲解。

Swagger-ui界面如下所示：访问http://localhost:8080/swagger-ui.html

方法2：使用官方依赖

步骤1、在pom.xml文件中添加swagger相关依赖

        <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>
            <version>2.7.0</version>
        </dependency>

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

步骤2、swagger的configuration

需要特别注意的是swagger scan base package，这是扫描注解的配置，即你的API接口位置。

package com.baidu.practice.config.swagger;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean(value = "restApi")
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("天气类接口文档")
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.baidu.practice.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("天气类接口")
                .description("各种类型的天气类接口汇总")
                .termsOfServiceUrl("")
                .version("2.0")
                .build();
    }

    @Bean
    public Docket smallHost(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("新闻类接口文档")
                .useDefaultResponseMessages(true)
                .apiInfo(smallHostApiInfo())
                .forCodeGeneration(false)
                .select()
                .paths(PathSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.baidu.practice.newscontroller"))
                .build();
    }

    private ApiInfo smallHostApiInfo(){
        return new ApiInfoBuilder()
                .title("新闻类接口")
                .description("各种类型的新闻类接口汇总")
                .version("3.0")
                .build();
    }
}

方法2同样可以达到方法1的效果，同样访问 http://localhost:8080/swagger-ui.html 这个路径，可以得到Swagger-ui界面，如上图所示