转载

微服务: Swagger让你可以多抽一支烟

Swagger ,可用于生成、描述、调用和可视化 RESTful 风格接口的API,是一套规范和完整的开发框架,并且能对接口进行单独测试。

另外, Swagger 在 Github 上面是开源的。

无论对于后端开发,还是前端开发以及测试同事,Swagger 都可以基本满足使用需求。

在 SpringBoot 中集成 Swagger,后端同事写完接口就可以自动生成API文档,可以给到前端同事看,测试同事可以直接测试该接口。

在本篇中,跟大家分享如下内容:

1、在 SpringBoot 中项目如何集成 Swagger?

2、如何使用 Swagger,如何在不同的环境中开启和关闭 Swagger?

3、如何将同类的接口使用 Swagger 注解进行聚合?

更多关于 SpringBoot 的文章,可以点击微服务项目系列文章 了解,完整代码示例请前往 Github 查看。

集成 Swagger

在 MavenEwpository 搜索 Springfox ,可以找到 Swagger2Swagger UI ,如图所示。

微服务: Swagger让你可以多抽一支烟

截止到目前, Swagger2Swagger UI 最新版本是 2.9.2 版本。

修改工程的pom文件,增加 Swagger2Swagger UI 的依赖,如下:

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

因为我的项目已经集成了 starter-web ,如下 pom 文件中的 dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

这样默认会集成 com.fasterxml.jackson.core: 相关的库,不需要额外再去集成 jackson-databind 了,如下图所示:

微服务: Swagger让你可以多抽一支烟

否则你需要单独增加 jackson-databind 的依赖,同样的道理你可以在 MavenEwpository 搜索 jackson-databind 选择合适的版本即可。

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.8</version>
</dependency>

工程已经集成了 Swagger ,接下来我们看看如何使用。

使用 Swagger

1、创建Swagger配置

新建一个配置类 MSSwaggerConfig ,该文件名称和位置你可以放到你的工程的任意目录,根据自己的项目目录来放置即可。

MSSwaggerConfig 示例代码如下:

@Configuration
@EnableSwagger2
public class MSSwaggerConfig{

    @Bean
    public Docket msblogDocket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        String pkgName = "com.veryitman.springboot.controller";
        return docket.apiInfo(msblogAPIInfo()).select()
                .apis(RequestHandlerSelectors.basePackage(pkgName))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo msblogAPIInfo(){
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        String apiTitle = "MSBlog Server API";
        String apiDes = "API for MSBlog";
        String apiVersion = "1.0.0";
        String homePage = "http://veryitman.com";
        String emailUrl = "veryitman@126.com";
        Contact contact = new Contact("itman", homePage, emailUrl);
        return apiInfoBuilder.title(apiTitle).description(apiDes)
                .version(apiVersion)
                .contact(contact)
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

记得添加 @Configuration@EnableSwagger2 这两个注解。

对于 apis(RequestHandlerSelectors.basePackage(pkgName)) 目的是只扫描指定包名下面 Controller 的 Swagger 注解,这样就不会去扫描其他包下面的类了。

对于这个配置类,主要是用来生成一些摘要信息,如图:

微服务: Swagger让你可以多抽一支烟

2、注解 Controller

在 微服务-简单的用户名注册和登录 给大家分享了如何写注册和登录的API,今天还是拿注册的例子来进行 Swagger 的演示。

下面代码是用户注册的示例代码。

@RestController
@RequestMapping(value = "signup")
public class MSSignupController{

    @CrossOrigin(origins = {"*"})
    @PostMapping(value = "/name")
    @ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "注册的用户名", required = true),
        @ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true)
    })
    public MSResponse signup(@RequestParam(value ="username")String userName, @RequestParam(value ="userpwd")String userPwd){
       // 省略
    }
}

可以看到如下的注解:

@ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册")
@ApiImplicitParams({
    @ApiImplicitParam(name = "username", value = "注册的用户名", required = true),
    @ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true)
})

这些注解就是 Swagger 的注解, @ApiOperation 说明了该接口的用途, @ApiImplicitParams 中有两个 @ApiImplicitParam 用来对接口的参数进行说明。

如果接口只有一个参数,可以直接使用 @ApiImplicitParam 注解即可。

3、在线文档

配置完成之后,可以启动 SpringBoot 项目,在浏览器中打开下面地址,就可以看到生成的在线文档了。

http://localhost:8080/swagger-ui.html#/

微服务: Swagger让你可以多抽一支烟

点击对应的 Controller 就可以看到对应接口的详细说明了,并且还可以对接口进行测试。

分环境开启 Swagger

在实际项目中,我们一般只会在开发和测试环境使能 Swagger,在沙盒和生成环境会关闭 Swagger,那如何控制呢?

在工程的 Resources 目录下面,新建几个跟环境相关的 properties 文件。

这些文件的命令要满足 application-{profile}.properties 的格式,其中 {profile} 你可以自定义名字,如下我自定义了4个环境,分别是开发、生产、沙盒和测试环境。

微服务: Swagger让你可以多抽一支烟

我们知道,在 application-{profile}.properties 中配置的选项与在 application.properties 中配置的选项如果名称相同,优先会使用 application-{profile}.properties 中配置。

application.properties 中配置如下:

# 配置使用哪个环境
spring.profiles.active=dev
# 默认不启用 swagger
swagger.enable=false

对应的在 application-dev.propertiesapplication-test.properties 中开启 swagger,如下:

# 启用 swagger
swagger.enable=true

选项配置完成后,我们在代码中使用该选项,修改 MSSwaggerConfig 如下(只列出了修改部分的关键代码):

@Configuration
@EnableSwagger2
public class MSSwaggerConfig{

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket msblogDocket(){
        Docket docket = 
        	new Docket(DocumentationType.SWAGGER_2).enable(enableSwagger);
        String pkgName = "com.veryitman.springboot.controller";
        return docket.apiInfo(msblogAPIInfo())
                .select()
                // 只扫描指定包名下面的Controller中的Swagger注解
                .apis(RequestHandlerSelectors.basePackage(pkgName))
                .paths(PathSelectors.any())
                .build();
    }

在下面的代码中读取配置

@Value("${swagger.enable}")
private boolean enableSwagger;

然后调用 Docket 的 enable(enableSwagger) 方法来决定是否开启 Swagger,如果配置不开启,效果图如下:

微服务: Swagger让你可以多抽一支烟

还有其他方式来控制在不同环境下配置 Swagger 是否开启,比如可以结合注解 @Profile 通过不同的 profile 给 Swagger 的依赖设置不同的 scope,还可以使用注解 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true") ,大家自行选择适合自己项目的方案即可,目的都是一样。

聚合接口

在上面实例中,我们可以看到登录和注册都属于用户模块,使用注解 @API 可以聚合显示这些接口。

在登录和注册的 Controller 中可以添加下面注解,从而来聚合显示接口。

@Api(value="xxx", tags="用户模块")

注册 Controller 添加注解,如下:

@Api(value="signup", tags="用户模块")
@RestController
@RequestMapping(value = "signup")
public class MSSignupController{
}

登录 Controller 添加注解,如下:

@Api(value="signin", tags="用户模块")
@RestController
@RequestMapping(value = "signin")
public class MSSigninController {
}

显示效果如下:

微服务: Swagger让你可以多抽一支烟

你眼睛看到的不一定是事实的全部~

微服务: Swagger让你可以多抽一支烟

原文  http://www.veryitman.com/2019/09/22/微服务-Swagger让你可以多抽一支烟/
正文到此结束
Loading...