springboot整合swagger。完爆前后端调试
<blockquote><p>web接口开发时在调试阶段最麻烦的就是参数调试，前端需要咨询后端。后端有时候自己也不是很了解。这时候就会造成调试一次接口就需要看一次代码。Swagger帮我们解决对接的麻烦</p>
</blockquote>
<h1 id="springboot接入swagger">springboot接入swagger</h1>
<ul>
<li>springboot 引入swagger只需要引入jar包，然后配置swagger启动。并配合swagger的注解使用就可以实现文档自动生成了。我们先来看看效果</li>
</ul>
<p><img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110246969-1840569309.jpg"></p>
<h2 id="环境准备">环境准备</h2>
<ul>
<li>
<p>代码还是基于spring仓库开发。分支为<code>feature/0004/springboot-swagger</code></p>
</li>
<li>
<p>swagger.version=2.9.2</p>
</li>
</ul>
<pre><code class="language-xml">
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
</code></pre>
<h2 id="配置">配置</h2>
<pre><code class="language-java">
@Configuration
@EnableSwagger2
public class SwaggerConfig2 {
@Bean
public Docket createRestApi() {
// 添加请求参数，我们这里把token作为请求头部参数传入后端
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
parameterBuilder.name("token").description("令牌")
.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
parameters.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com"))
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build().apiInfo(new ApiInfoBuilder()
.title("后端服务说明")
.description("SpringBoot整合Swagger，详细信息......")
.version("1.0")
.contact(new Contact("zxhtom", "zxhtom.blog.csdn.net", "870775401@qq.com"))
.license("The Apache License")
.licenseUrl("http://zxhtom.gitee.io")
.build())
.useDefaultResponseMessages(false)
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.globalOperationParameters(parameters);
}
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey("Authorization", "token", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope;
authorizationScopes = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
</code></pre>
<h3 id="添加请求头">添加请求头</h3>
<pre><code class="language-java">
securitySchemes(securitySchemes())
securityContexts(securityContexts())
</code></pre>
<ul>
<li>在上面的两端配置就是加入全局的token设置的。在swagger-ui界面显示是右上角有一把锁的标志</li>
</ul>
<p><img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110247554-1615857108.png"><br>
<img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110247791-1775998358.png"><br>
<img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110248049-393551164.png"></p>
<h3 id="接口使用">接口使用</h3>
<p><img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110248274-1120321066.png"><br>
<img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110248488-320799855.png"><br>
<img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110248683-1391629584.png"></p>
<h2 id="注解使用">注解使用</h2>
<table>
<thead>
<tr>
<th>注解</th>
<th>功能</th>
</tr>
</thead>
<tbody>
<tr>
<td>@Api()</td>
<td>用在请求的类上。表示该类的请求类用于文档标注</td>
</tr>
<tr>
<td>@ApiOperation()</td>
<td>用于方法上。对一个http请求的具体说明，出参入参说明</td>
</tr>
<tr>
<td>@ApiModel()</td>
<td>对请求实体的一个说明</td>
</tr>
<tr>
<td>@ApiModelProperty</td>
<td>对实体内属性说明，也可以设置默认值</td>
</tr>
<tr>
<td>@ApiImpliciParams()</td>
<td>用于请求的方法上，里面是ApiImpliciParam数组</td>
</tr>
<tr>
<td>@ApiImpliciParam()</td>
<td>表示单独请求参数。可以设置form表单中参数单独设置</td>
</tr>
<tr>
<td>@ApiParam()</td>
<td>对请求方法中参数的单独设置 类似ApiImpliciParam</td>
</tr>
<tr>
<td>@ApiResponses()</td>
<td>对请求方法上根据响应码设置说明</td>
</tr>
<tr>
<td>@ApiResponse</td>
<td>单个响应码说明</td>
</tr>
<tr>
<td>@ApiIgnore()</td>
<td>对该请求的忽略</td>
</tr>
</tbody>
</table>
<ul>
<li>具体使用可以查看源码。源码上面有给出。</li>
</ul>
<h1 id="自定义swaggerui">自定义swaggerUI</h1>
<ul>
<li>这里需要首先介绍下spring资源的加载顺序。</li>
</ul>
<p>src/main/resources/META-INF/resources<br>
src/main/resources/static<br>
src/main/resources/public</p>
<ul>
<li>这三个优先级依次降低。欢句话说spring首先会在src/main/resources/META-INF/resources下寻找资源。所以这也是我们自定义swaggerUI的策略。我们只需要在META-INF下重新绘画swaggerUI的页面就行了。这里只是提供思路。不具体实现(懒)</li>
</ul>
<p>加入战队</p>
<h1 id="-加入战队"># <span id="addMe">加入战队</span></h1>
<h2 id="微信公众号">微信公众号</h2>
<p><img src="https://img2020.cnblogs.com/blog/1002125/202103/1002125-20210310110248818-573588114.jpg"></p><br><br>
来源：https://www.cnblogs.com/zhangxinhua/p/13327864.html
頁:
[1]