springbootはswagger2を統合します
SpringMVCがSpringfox-swagger2を統合してRESTfulAPIを構築したという記事は、 swagger2をspringmvcに統合する 方法を記述しただけです。swagger2をspringbootに統合する方法は次のとおりです。実際、使用法は基本的に同じです。
1.依存関係を導入する
mavenを使用して、pom.xml(swaggerバージョン2.4.0、springbootバージョン2.1.5.RELEASE)で関連する依存関係を参照します。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
次に、Swaggerの構成クラスを作成します
この構成クラスは、springmvcの記述とまったく同じです。
package com.xingguo.springboot;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xingguo.springboot.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf(){
return new ApiInfoBuilder()
.title("xingguo大标题")
.description("springboot swagger2")
.termsOfServiceUrl("http://blog.csdn.net/u014231523网址链接")
.contact(new Contact("diaoxingguo", "http://blog.csdn.net/u014231523", "[email protected]"))
.build();
}
}
その中で、RequestHandlerSelectors.basePackage(xxx)を変更する必要があることに加えて、他の構成を変更する必要はありません。
元のバージョン2.2.0では、新しいApiInfo()を使用する方法が古くなっています。新しいApiInfoBuilder()を使用して構築し、必要なパラメーターを追加します。もちろん、すべてを追加できます。といった:
private ApiInfo buildApiInfo(){
return new ApiInfoBuilder().build();
}
3、コントローラーに関連する注釈を追加します
一般的に使用されるアノテーションは次のとおりです。-
クラス名の
@Api()-メソッド名の
@ApiOperation()-パラメータの説明の
@ApiParam()-エンティティクラスの
@ApiModel ()-エンティティクラス属性の@ApiModelProperty
詳細な意味については、公式の説明wikiを参照してください 。コードとサンプル画像は以下で使用されます。
第四に、プロジェクトを開始します
ブラウザでURLを入力します:http:// {ip}:{port} /swagger-ui.html#/、URLに#/を入力する必要はありません
application.propertiesのポート番号を9090に設定します(設定されていない場合、デフォルトは8080です)
server.port=9090
したがって、URLは次のようになります:http:// localhost:9090 / swagger-ui.html、図に示すように:
ここでは、対応するパッケージの下のすべてのコントローラーがカテゴリ(タグまたは@Api)ごとに表示されます。
5、サンプルコード
UserController.javaクラスの1つを見てみましょう(ビジネスロジックは無視して、コメントだけを見てください)
package com.xingguo.springboot.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import javax.annotation.Resource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import com.xingguo.springboot.model.User;
import com.xingguo.springboot.service.UserService;
@Api(value="用户controller",description="用户操作",tags={"用户操作接口"})
@RestController
public class UserController {
@Resource
private UserService userService;
@ApiOperation("获取用户信息")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
User user = userService.getUserInfo();
return user;
}
@ApiOperation("更改用户信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
int num = userService.updateUserInfo(user);
return num;
}
@ApiOperation("添加用户信息")
@PostMapping("/saveUser")
public String saveUser(@RequestBody @ApiParam(name="user",value="json fromat",required=true) User user) {
userService.saveUser(user);
return "success";
}
}
ここでは、オブジェクトをパラメータとして使用する場合、対応する注釈をオブジェクトに追加すると、ユーザーページが表示されることを説明します。といった:
package com.xingguo.springboot.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
@ApiModel(description="用户对象user")
public class User {
@ApiModelProperty(value="用户名",name="username")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
private String[] ids;
private List<String> idList;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getState() {
return state;
}
public void setState(Integer state) {
this.state = state;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String[] getIds() {
return ids;
}
public void setIds(String[] ids) {
this.ids = ids;
}
public List<String> getIdList() {
return idList;
}
public void setIdList(List<String> idList) {
this.idList = idList;
}
public String getNickName() {
return nickName;
}
public void setNickName(String nickName) {
this.nickName = nickName;
}
public Integer getIsDeleted() {
return isDeleted;
}
public void setIsDeleted(Integer isDeleted) {
this.isDeleted = isDeleted;
}
}
表示される効果は次のとおりです。
上の図の赤いボックス(そのうちの1つはjson形式)を見て、クリックしてパラメーター形式を取得します。
2番目のシートでは、フィールドの対応するコメントと、それらが必須かどうかを確認できます。注釈@ApiModelProperty(required = true)をフィールドに追加すると、それは必須であり(デフォルトはfalse)、対応するページのオプションのロゴも消え、このフィールドは必須です。
下の[試してみる]ボタンをクリックすると、デバッグできます。
上記のコードでgetUserInfo()メソッドなどの単一のパラメーターを使用する場合、対応する効果図は次のようになります
。required= trueをここに追加すると、@ ApiParam(required = true)はページに必要なロゴを表示します。同じデフォルトはfalseです。自分で他の使い方を試すことができます。