程序员社区

Spring Boot中使用Swagger2

使用RESTful服务通常是涉及到多个终端的团队,比如Android、iOS、WEB等。为了让大家沟通顺畅,通常我们需要编写一份详细的RESTful业务接口文档

使用Swagger2有助于我们编写一份详细的RESTful业务接口文档,过去经常会使用Word或者Excel,但是接口非常多,细节又复杂,如果由程序员高质量的输出一个文档,经常耗时长而且效果也不好。Swagger2能将代码和注释说明很好结合在一块。既减轻了研发人员的负担,又能输出高质量的文档。
下面说下如何去使用

pom.xml中添加Swagger2依赖

2.6.1版本是16年11月才更新的版本

<!--引入Swagger2的依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

创建Swagger2配置类

@Configuration注解,让Spring来加载该类配置。
@EnableSwagger2注解来启用Swagger2。
apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
RequestHandlerSelectors.basePackage()中填的是你controller的目录
apiInfo()方法中termsOfServiceUrlcontact可以用Contact的对象代替
Swagger2已经不支持String类型的contact

Spring Boot中使用Swagger2插图
Paste_Image.png

Contact对象中name表示作者,url通常作为项目的链接,代替之前的termsOfServiceUrl方法,email的话不用我多说了吧,不想写的话可以为空字符串

Spring Boot中使用Swagger2插图1
Paste_Image.png

createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。

@Configuration
@EnableSwagger2
public class Swagger2 {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    private ApiInfo apiInfo() {
        Contact contact=new Contact("作者名",
          "http://www.jianshu.com/u/f192766abeab","email地址");
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("Hello Swagger2")
                //.termsOfServiceUrl("http://www.jianshu.com/u/f192766abeab")
                //.contact("作者名")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

然后通过创建实体类和controller来简单测试下
具体的可以参照

简书作者 程序猿DD的文章Spring Boot中使用Swagger2构建强大的RESTful API文档

http://www.jianshu.com/p/8033ef83a8ed

注意

记得在UserController中需要id输入的方法的注解少了个参数配置: paramType="path",不然所有的参数类型都会是body,获取不到请求参数。例如
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path")

访问:http://localhost:8080/swagger-ui.html
就能看到前文所展示的RESTful API的页面。

Spring Boot中使用Swagger2插图2
Paste_Image.png

选中所写的UserController后出现5个方法让你测试

Spring Boot中使用Swagger2插图3
Paste_Image.png

具体的测试效果可以自己来测试玩玩

赞(0) 打赏
未经允许不得转载:IDEA激活码 » Spring Boot中使用Swagger2

相关推荐

  • 暂无文章

一个分享Java & Python知识的社区