springboot配置swagger-rest文档

前言

swagger是一个很好的restful形式的api文档，可以通过比较小的侵入来提供很好的restful的文档。因为swagger是依赖服务生成的，所以其实是依赖服务的，这也算是它的一个小缺点吧。但是其实如果一个项目习惯去手写文档之后，也是可以的，但是新的项目还是建议去用一些自动生成的文档，省去了很多麻烦。

spring boot配置swagger

引入swagger依赖

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.2.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.2.2</version>

</dependency>

编写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 {
@<span class="hljs-type">Bean</span>

<span class="hljs-keyword">public</span> <span class="hljs-type">Docket</span> createRestApi() {

                <span class="hljs-comment">// 文档类型</span>

    <span class="hljs-keyword">return</span> new <span class="hljs-type">Docket</span>(<span class="hljs-type">DocumentationType</span>.<span class="hljs-type">SWAGGER_2</span>)

            <span class="hljs-comment">// 创建api的基本信息</span>

            .apiInfo(apiInfo())

            <span class="hljs-comment">// 选择哪些接口去暴露</span>

            .select()

            <span class="hljs-comment">// 扫描的包</span>

            .apis(<span class="hljs-type">RequestHandlerSelectors</span>.basePackage(<span class="hljs-string">"com.demo.web.controller"</span>))

            .paths(<span class="hljs-type">PathSelectors</span>.any())

            .build();

}

<span class="hljs-keyword">private</span> <span class="hljs-type">ApiInfo</span> apiInfo() {

    <span class="hljs-keyword">return</span> new <span class="hljs-type">ApiInfoBuilder</span>()

            .title(<span class="hljs-string">"groundhog-web swagger文档"</span>)

            .contact(<span class="hljs-string">"name"</span>)

            .version(<span class="hljs-string">"1.0"</span>)

            .build();

}


}

在api和请求参数中使用注解

接口中使用swagger注解

@RestController

@Api(value = "测试swagger", description = "测试swagger api")

public class TestSwaggerController {
<span class="hljs-variable">@ApiOperation</span>(value = <span class="hljs-string">"返回url中的参数"</span>, notes = <span class="hljs-string">"返回url中的参数"</span>)

<span class="hljs-variable">@ApiImplicitParam</span>(name = <span class="hljs-string">"id"</span>, value = <span class="hljs-string">"id值"</span>, paramType = <span class="hljs-string">"path"</span>, required = true, dataType = <span class="hljs-string">"Integer"</span>)

<span class="hljs-variable">@GetMapping</span>(path = <span class="hljs-string">"/getUrlParam/{id}"</span>)

public Integer getUrlParam(<span class="hljs-variable">@PathVariable</span>(value = <span class="hljs-string">"id"</span>) Integer id) {

    <span class="hljs-selector-tag">return</span> <span class="hljs-selector-tag">id</span>;

}


}

可以访问localhost:port/swagger-ui.html看到生成的swagger文档。可以看到请求结果：

也可以看到之前post方法的接口也可以生成对于的参数文档，这里也可以对表单参数bean使用@ApiModel和@ApiProperty注解进行标识。

swagger相关注解和官方文档

swagger常用注解：

@Api：修饰整个类，描述controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

这里推荐下官方文档，感兴趣可以看一下其他注解和相关配置：

[注解官方文档](

               原文地址：https://blog.csdn.net/zlj1217/article/details/82829891                 </div>

巴特西