springboot 使用swagger生成接口説明文檔
Posted iTachiLEe
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了springboot 使用swagger生成接口説明文檔相关的知识,希望对你有一定的参考价值。
1 創建一個新的mvn項目並添加核心依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- swagger2 api tools--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- end-->
2 創建swagger配置類:
package com.reason.gsny.config; import com.google.common.collect.Sets; 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; /** * api 文档与测试 * 访问地址为: http://ip:port/swagger-ui.html * @author leon */ @Configuration // 开启swagger api文档 @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) //协议,http或https .protocols(Sets.newHashSet("http")) .apiInfo(apiInfo()) .select() //会在这个路径下扫描controller定义 .apis(RequestHandlerSelectors.basePackage("com.reason.gsny")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("REST接口定义") .version("1.0") .description("用于测试RESTful API") .build(); } }
3 在api方法中使用 @ApiOperation 注解
package com.reason.gsny.api; import com.reason.gsny.entity.jwt.AuthenticationRequest; import com.reason.gsny.entity.jwt.AuthenticationResponse; import com.reason.gsny.support.MyUserDetailsService; import com.reason.gsny.util.JwtUtil; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.security.authentication.AuthenticationManager; import org.springframework.security.authentication.BadCredentialsException; import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/v1") public class AuthenticateApi { // @ApiOperation用於生成api文檔説明 @ApiOperation(value="helloWorld", notes="helloWorld 詳情説明") @ResponseStatus(HttpStatus.OK) @RequestMapping(value = "/helloWorld", method = RequestMethod.POST) public String hello { return "helloWorld"; } }
4 啓動springboot,訪問 http://ip:port/swagger-ui.html 即可
5 錯誤處理:打不開swagger-ui文檔説明頁面,可能的原因是springboot的靜態資源文件攔截:
package com.reason.gsny.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; /** * 靜態資源配置 */ @Configuration public class StaticResourceConfiguration implements WebMvcConfigurer { private static final String[] CLASSPATH_RESOURCE_LOCATIONS = { // "classpath:/build/", "classpath:/META-INF/*/", "classpath:/resources/", "classpath:/static/", "classpath:/public/", }; @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**") .addResourceLocations(CLASSPATH_RESOURCE_LOCATIONS); // 重新注冊swagger的靜態資源地址 registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
6 生產markdown與ascii説明文檔
首先添加依賴
<dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency>
package com.reason.gsny; import io.github.swagger2markup.GroupBy; import io.github.swagger2markup.Language; import io.github.swagger2markup.Swagger2MarkupConfig; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder; import io.github.swagger2markup.markup.builder.MarkupLanguage; import org.junit.jupiter.api.Test; import org.springframework.boot.test.context.SpringBootTest; import java.net.URL; import java.nio.file.Paths; /** * 訪問本地api地址 * 我的端口是1978,故訪問 http://127.0.0.1:1978/v2/api-docs * @author leon */ @SpringBootTest class GsnyApplicationTests { @Test void contextLoads() { } /** * 生成AsciiDocs格式文档 * @throws Exception */ @Test public void generateAsciiDocs() throws Exception { // 输出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://127.0.0.1:1978/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated")); } /** * 生成Markdown格式文档 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 输出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:1978/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Confluence格式文档 * @throws Exception */ @Test public void generateConfluenceDocs() throws Exception { // 输出Confluence使用的格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:1978/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成AsciiDocs格式文档,并汇总成一个文件 * @throws Exception */ @Test public void generateAsciiDocsToFile() throws Exception { // 输出Ascii到单文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:1978/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文档,并汇总成一个文件 * @throws Exception */ @Test public void generateMarkdownDocsToFile() throws Exception { // 输出Markdown到单文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:1978/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); } }
注意 需要啓動springboot后再運行測試,否則會找不到網址而抛出異常
以上是关于springboot 使用swagger生成接口説明文檔的主要内容,如果未能解决你的问题,请参考以下文章
SpringBoot SpringBoot整合Swagger2(自动化生成接口文档)