为了账号安全,请及时绑定邮箱和手机立即绑定

Spring Boot 集成 Swagger,生成接口文档就这么简单!

标签:
Java

之前的文章介绍了《推荐一款接口 API 设计神器!》,今天栈长给大家介绍下如何与优秀的 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) {
    
        // ...
          
    }
}

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

关注Java技术栈微信公众号,获取栈长整理的更多的工具绝技,都是实战干货,以下仅为部分预览。

  • Java 开发必知道的国外 10 大网站
  • 免费在线创作流程图、思维导图软件
  • 推荐一款代码神器,代码量至少省一半!
  • 推荐一款接口 API 设计神器!
  • 超详细的 Git 实战教程,傻瓜一看也会!
  • ……
点击查看更多内容
TA 点赞

若觉得本文不错,就分享一下吧!

评论

作者其他优质文章

正在加载中
全栈工程师
手记
粉丝
1.4万
获赞与收藏
1957

关注作者,订阅最新文章

阅读免费教程

  • 推荐
  • 评论
  • 收藏
  • 共同学习,写下你的评论
感谢您的支持,我会继续努力的~
扫码打赏,你说多少就多少
赞赏金额会直接到老师账户
支付方式
打开微信扫一扫,即可进行扫码打赏哦
今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与 放弃机会
意见反馈 帮助中心 APP下载
官方微信

举报

0/150
提交
取消