Spring Boot 集成 Swagger,再也不写接口文档了!

扫码关注公众号:Java 技术驿站

发送:vip
将链接复制到本浏览器,永久解锁本站全部文章

【公众号:Java 技术驿站】 【加作者微信交流技术,拉技术群】
免费领取10G资料包与项目实战视频资料

今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单。

Spring Boot 集成 Swagger

1、添加依赖

Maven依赖示例:

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

2、在 Spring Boot 配置文件中添加配置参数。

    swagger:
      title: API标题
      description: API描述
      version: 1.0
      terms-of-service-url: http://www.javastack.cn/
      base-package: cn.javastack.test.web
      contact:
        name: Javastack
        url: http://www.javastack.cn/
        email: admin@javastack.cn

3、添加配置类

    @Getter
    @Setter
    @Configuration
    @EnableSwagger2
    @ConditionalOnClass(EnableSwagger2.class)
    @ConfigurationProperties(prefix = "swagger")
    public class SwaggerConfig {

        /**
         * API接口包路径
         */
        private String basePackage;

        /**
         * API页面标题
         */
        private String title;

        /**
         * API描述
         */
        private String description;

        /**
         * 服务条款地址
         */
        private String termsOfServiceUrl;

        /**
         * 版本号
         */
        private String version;

        /**
         * 联系人
         */
        private Contact contact;

        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage(basePackage))
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title(title)
                    .description(description)
                    .termsOfServiceUrl(termsOfServiceUrl)
                    .version(version)
                    .contact(contact)
                    .build();
        }

    }

如何使用

Swagger 默认会根据配置的包,扫描所有接口并生成对应的 API 描述和参数信息,但这样不是很直观,需要对每个接口和参数进行自定义描述。

常用的 Swagger 注解如下。

注解名称 使用说明
@Api 描述一个API类
@ApiImplicitParam 描述一个请求参数
@ApiImplicitParams 描述一组请求参数
@ApiModel 描述一个返回的对象
@ApiModelProperty 描述一个返回的对象参数
@ApiOperation 描述一个API方法
@ApiParam 描述一个方法的参数
@ApiResponse 描述一个请求响应
@ApiResponses 描述一组请求响应

使用示例如:

    @Api(description = "登录模块")
    @RestController
    public class LoginController {

        @ApiOperation(value = "登录", httpMethod = "POST")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query"),
                @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query")})
        @PostMapping(value = "/login")
        public Object login(@RequestParam("username") String username, @RequestParam("password") String password) {

            // ...

        }
    }

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

打开 swagger-ui 界面,可以看到所有的 API 接口定义,也可以在上面发起接口测试。


来源:https://cloud.tencent.com/developer/column/2205/tag-10712

赞(0) 打赏
版权归原创作者所有,任何形式的转载请联系博主:daming_90:Java 技术驿站 » Spring Boot 集成 Swagger,再也不写接口文档了!

  • 暂无文章

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏